Create datasets in Postman

Use datasets to manage and use data across your API workflows in Postman. You can run data-driven collection tests, power dynamic mock responses, and reuse the same data across scripts. Datasets also enable you to work with both data files and live data from external systems, so you can test different scenarios without duplicating or managing data in multiple places.

About datasets

A dataset is a set of data you can use across your API workflows. Each dataset is stored in a YAML file and organized into data sources and views:

• Data sources define where the data comes from, including CSV, JSON, or spreadsheet data files (locally or in the Postman Cloud), external connections like MySQL, Postgres, or SQL Server, or custom database connections using a JDBC driver.
• Views are SQL queries that define how data is retrieved from data sources. They enable you to select, filter, and combine data so it works with your tests, scripts, and mocks. Views support SQLite-compatible SQL syntax and functions.

Create a dataset

Create a dataset to use across your collection runs, code mocks, and scripts. A dataset can include multiple data sources, from data files (static) or live data (dynamic), such as MySQL, Postgres, SQL Server, or any database with a JDBC driver.

To create a dataset, do the following:

1. In the left sidebar, click and select Dataset.
2. (Optional) Enter a name and description for your dataset.
3. Select the data source type you’d like to add. You can’t change a data source’s type after you create it.
4. Configure the data source and add it to your dataset. The steps depend on the data source type.
5. (Optional) Add more data sources to combine different types of data in your workflows.

A view is automatically created for each data source that selects all of the data. You can manage your data sources and views as your workflows change. This enables you to support new scenarios, combine data from different sources, and control how data is used across tests, scripts, and mocks. Learn more about managing datasets.

About the dataset file

In the Postman desktop app in Local View, Postman generates a YAML file that defines its data sources and views. The file also includes metadata about the dataset, such as its name and ID. This file is stored in your local Git repository and serves as the source of truth for your dataset configuration.

Any changes you make to the dataset in Postman are reflected in this file, and updates to the file are reflected in Postman. You can use it to review changes and manage your dataset in version control.

The dataset file is located at /postman/datasets/<dataset-name>/<dataset-name>.dataset.yaml.

Data source types

You can add multiple data sources to a dataset. The following data source types are available: Postman Cloud Store, Local File, MySQL, Postgres, SQL Server, custom data sources using a JDBC driver, and AI-generated data files.

The data source types you can add depend on whether you’re using the Postman desktop app or the Postman web app:

• Postman desktop app — You can add all data source types: Postman Cloud Store, Local File, MySQL, Postgres, SQL Server, and custom JDBC data sources.
• Postman web app — You can add Postman Cloud Store, MySQL, and Postgres. You can’t add local files, SQL Server, or custom JDBC data sources.

Data file

You can add a data file as a data source. Postman supports CSV, JSON, and spreadsheet (.xlsx, .xls, and .ods) files. If a spreadsheet has multiple sheets, Postman adds each sheet as a separate data source. You can add a file in two ways:

• Local File — Add a file from your local machine. In Local View, select the Copy file to repository checkbox (selected by default) to copy the file into your local Git repository, so it’s included in your workspace, can be shared with others, and can be modified by Agent Mode with sample data. Consider turning this off for large files. In Cloud View, the file stays on your machine, so use Postman Cloud Store if you need to access it across devices, users, and cloud runs.
• Postman Cloud Store — Add a file from your local machine and upload it to the Postman Cloud Store, so it’s available across devices, users, and cloud runs.

To add a data file, do the following:

1. Select Local File or Postman Cloud Store.
2. Choose a file from your local machine, or drag and drop it into the workbench.
3. Preview the data, then click Save. Spreadsheet files can’t be previewed, but you can still add them as a source.

External data source

You can connect to MySQL, Postgres, or SQL Server as an external data source. If your data source is behind a firewall or not publicly accessible, you can connect through an SSH tunnel. When using an SSH tunnel, the data source must be accessible from the SSH server’s network.

1. Select MySQL, Postgres, or SQL Server.

2. Enter the following connection details:

   • Host — The hostname or IP address of the database server.
   • Port — The port number for the database server.
   • Database — The name of the database to connect to.
   • Username — The username to authenticate with the database.
   • Password — The password to authenticate with the database.
   • Table — The name of the table to connect to.
   • Schema — The name of the schema to connect to. Postgres and SQL Server only.

3. (Optional) Select Connect through an SSH tunnel and enter the following:

   • SSH host — The hostname or IP address of the SSH server.
   • SSH port — The port number for the SSH server.
   • SSH username — The username to connect to the SSH server.
   • SSH private key — The private key to authenticate with the SSH server. Click Choose a file to select a file, or paste the key directly.
   • SSH host key — The host key of the SSH server. Click Choose a file to select a file, or paste the key directly.
   • (Optional) Select Skip SSH host key verification — Skips verification of the SSH server’s host key. This can expose the connection to man-in-the-middle attacks. Use only for non-production testing.

4. Click Test connection to verify the connection details are correct and Postman can connect to it. If the connection fails, check that your connection details are correct and your network allows connections to the data source.

Store sensitive data, such as the host and password, as vault secrets in Postman Vault. Click Link to vault secret next to a field that accepts sensitive data and select a vault secret to use. To update a vault secret, click Unlink vault secret next to a field to remove the vault secret.

Custom data source

You can connect to any database system that has a JDBC (Java Database Connectivity) driver by adding a custom data source. This is useful when your database isn’t available as a built-in source type. When you add a custom data source, Postman saves the driver configuration as a reusable type. For the databases Postman supports through JDBC, see Databases supported through JDBC.

To add a custom data source, do the following:

1. Select JDBC Source.
2. Driver — Upload a JDBC driver JAR, name the driver configuration, and select the driver class.
3. Connection URL — Select a URL pattern and define the connection template.
4. Data source — Name the source, fill in connection values, and add it to your dataset.

Step 1: Driver

Upload a JDBC driver JAR file and configure the driver type that Postman will use to connect to your database.

1. Under Driver JAR, click Browse and select a JDBC driver JAR file from your local machine. After selecting a file, click Change to select a different one.

   Postman reads the JAR and displays the number of driver classes found. It also autodetects a compatible Java runtime on your PATH.

   If you need a different runtime, click Use a different runtime and provide the path to the Java binary.

2. In the Type name field, enter a name to identify this driver configuration in your dataset. Choose a name that reflects the database system, for example, “MySQL JDBC”.

3. Under Driver class, select the driver class from the list of classes detected in the JAR. The driver class is the implementation class that handles communication with your database. If the JAR contains multiple driver classes, select the one appropriate for your database system, for example, com.mysql.cj.jdbc.Driver.

4. Click Next.

Step 2: Connection URL

Select a URL pattern and define the JDBC connection string template Postman will use to connect to your database.

1. Select a URL pattern. Postman autodetects the pattern from the driver and preselects it. If it can’t detect one, it selects Generic. For a complete list of supported patterns and their URL formats, see Supported URL patterns.

2. Review or update the JDBC URL template. This updates based on the URL pattern you selected. For example:

   jdbc:mysql://{{host}}:{{port}}/{{database}}

   You can customize the template. Use {{variable}} syntax for values that vary per connection. Enter {{ in the template field for suggestions, or click a suggestion below the field to add it. Suggestions are based on configuration properties detected from the JAR.

3. Click Next. Postman extracts the variables from your template and displays them as individual fields in the next step.

Step 3: Data source

Name the data source, fill in the connection variable values from your URL template, and add it to your dataset.

1. In the Source name field, enter a name for this data source.

2. Under Connection, enter the value for each variable defined in your URL template, such as host, port, and database name. To use a vault secret as the value, select an existing secret from the dropdown. After entering a value, click New secret to save it as a vault secret and select the vault type where it’s stored.

3. (Optional) Select Connect through an SSH tunnel and enter the following:

   • SSH host — The hostname or IP address of the SSH server.
   • SSH port — The port number for the SSH server.
   • SSH username — The username to connect to the SSH server.
   • SSH private key — The private key to authenticate with the SSH server. Click Choose a file to select a file, or paste the key directly.
   • SSH host key — The host key of the SSH server. Click Choose a file to select a file, or paste the key directly.
   • (Optional) Select Skip SSH host key verification — Skips verification of the SSH server’s host key. This can expose the connection to man-in-the-middle attacks. Use only for non-production testing.

4. Click Test connection to verify the connection details are correct and Postman can connect to it. If the connection fails, check that your connection details are correct and your network allows connections to the data source.

5. Click Add source.

Store sensitive data, such as the host and password, as vault secrets in Postman Vault. Click Link to vault secret next to a field that accepts sensitive data and select a vault secret to use. To update a vault secret, click Unlink vault secret next to a field to remove the vault secret.

Supported URL patterns

The following URL patterns are available when configuring a JDBC connection. Postman autodetects the pattern from the driver where possible.

• MySQL — jdbc:mysql://{{host}}:{{port}}/{{database}}
• Postgres — jdbc:postgresql://{{host}}:{{port}}/{{database}}
• SQL Server — jdbc:sqlserver://{{host}}:{{port}};databaseName={{database}}
• Oracle — jdbc:oracle:thin:@{{host}}:{{port}}:{{database}}
• Generic — No default template. Enter a JDBC URL template appropriate for your database system.

Databases supported through JDBC

Postman supports the following databases through JDBC. This list isn’t exhaustive. You can connect to any database that provides a JDBC driver.

• Amazon DynamoDB
• Apache Cassandra
• Apache Derby
• Apache Doris
• Apache Ignite
• Apache IoTDB
• Apache Pinot
• Apache Solr
• ClickHouse
• CockroachDB
• CrateDB
• CUBRID
• DuckDB
• Elasticsearch
• Firebird
• Google Cloud Spanner
• H2
• HSQLDB
• MariaDB
• Materialize
• Microsoft Access
• Microsoft SQL Server
• MonetDB
• MongoDB
• MySQL
• Neo4j
• OpenLink Virtuoso
• OpenSearch
• Oracle Database
• PostgreSQL
• Presto
• QuestDB
• Redis
• SQLite
• StarRocks
• TDengine
• Trino
• YugabyteDB

Add with AI

You can use Agent Mode to generate data and add it as a new data source. Describe the data you need, such as sample users, order records, or API test fixtures. Agent Mode guides you through defining the schema and generating the rows.

To add a data source with AI, do the following:

1. Select Add with AI. Agent Mode opens with a prompt to help you define your data.
2. Describe the data you want to generate.
3. Review and confirm the proposed schema. Agent Mode presents how each field will be generated before producing any rows.
4. After confirming, Agent Mode generates the rows and shows a preview of up to five sample rows.
5. Review the sample. Agent Mode saves the generated data as a CSV file and adds it as a new data source in your dataset.