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 use SQLite-compatible SQL syntax and functions, except for custom JDBC sources and database sources used without a table, which use the connected database’s native dialect.

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. Custom data sources are an exception. Because Postman doesn’t interpret the connected database’s SQL dialect, you write their views yourself. 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.

You can also create a dataset when you configure a collection run, performance test, or monitor.

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 — (Optional) The name of the table to connect to, or leave it blank to connect to the whole database.
   • 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

Postman provides built-in connectors for MySQL, Postgres, and SQL Server. A custom data source connects your dataset to any other database system through a JDBC (Java Database Connectivity) driver that you supply. JDBC is a standard interface for database access, and most commercial, open-source, and internal database systems publish a driver for it. This means you can use a database such as Oracle, Snowflake, or an internal system as dataset data without waiting for Postman to add a built-in connector. For the databases Postman supports through JDBC, see Databases supported through JDBC.

Postman doesn’t provide database drivers or a Java runtime. You download the driver for your database, and the machine that queries the data source needs Java installed. Postman runs the driver in a separate Java process and sends your SQL to it unchanged. That’s why views on a custom data source use your database’s own SQL dialect. When you add a custom data source, Postman saves the driver configuration as a reusable type you can select for other data sources in the same dataset.

Before you add a custom data source, make sure you have the following:

• A JDBC driver JAR file for your database — Download the driver from your database vendor.
• Java 8 or newer — Java 17 is recommended. Install it on the machine that queries the data source.

To add a custom data source, do the following:

1. Select JDBC Source.
2. Driver — Select the JDBC driver JAR files, confirm your Java runtime, name the driver configuration, and select the driver class.
3. Connection URL — Review or write the JDBC URL template.
4. Data source — Name the source, fill in connection values, and add it to your dataset.

Step 1: Driver

Select the JDBC driver JAR files and configure the driver type that Postman will use to connect to your database.

1. Under Driver JARs, click Browse and select a JDBC driver JAR file from your local machine. Click Add JAR to add any dependency JAR files the driver needs.

   Postman loads the driver, reports how many compatible driver classes it found, and checks your Java runtime.

   If your driver needs dependency JAR files, add them in the order the driver expects. Java resolves classes in the order they’re listed, and you can’t reorder the list after you add the files. To start over, click Change and select the files again. Change clears every file you’ve added, not only the first one.

2. Confirm the Java runtime. Postman automatically detects Java using the JAVA_HOME environment variable and then your PATH, then reports the version it verified. Java 8 or newer is required, and Java 17 is recommended.

   To use a different runtime, enter the path to a Java executable or to a JDK or JRE home directory in Java executable or runtime directory, then click Verify. Postman stores this path on your machine only and doesn’t save it to the dataset file.

3. In the Type name field, review the name that identifies this driver configuration in your dataset. Postman fills this in from the JAR file name. You can change it to a name that reflects the database system, for example, “MySQL JDBC”.

4. 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.

5. Click Next.

Step 2: Connection URL

Define the JDBC connection string template Postman uses to connect to your database. Every database system addresses things differently, such as schemas, service names, and instances, so the template describes the URL format your database expects.

1. Review the JDBC URL template. When Postman recognizes your driver, it fills in a template for you. For example, selecting a MySQL driver gives you:

   jdbc:mysql://{{host}}:{{port}}/{{database}}?user={{user}}&password={{password}}

   To use a different template, click in the field and select a database system from the list. For the templates Postman suggests, see Supported URL patterns.

2. Edit the template if your database needs a different URL format. Use {{variable}} syntax for values that vary per connection. Enter {{ in the template field to filter the suggestions, or click a suggestion below the field to insert it. Suggestions are based on configuration properties detected from the JAR.

   Under Configuration variables to be filled in next, Postman lists the variables it found in your template. These become the fields you complete in the next step.

3. Click Next.

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, database name, and credentials. 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.

Where custom data sources run

Whichever machine queries a custom data source is the machine that runs Java and the driver. Postman saves the driver configuration with the dataset, but it doesn’t upload the driver JAR file. Each machine that uses the dataset needs its own copy of the driver and its own Java runtime.

Where that copy has to live depends on what’s running the dataset. The Postman desktop app and the Postman CLI look for the driver at the path saved in the dataset. A runner looks only in a folder you specify when you start it.

• Postman desktop app — Supported. The Postman web app can’t add or use custom data sources.
• Postman CLI — Supported.
• Monitors — Supported on a Private API Monitoring runner. Monitors that run in the Postman Cloud can’t use custom data sources. Learn more about using a dataset with a monitor.

Supported URL patterns

When you click in the JDBC URL template field, Postman suggests a template for each of the following database systems. Postman fills in a template automatically when it recognizes your driver. You can edit any template, and you can connect to a database that isn’t listed by writing your own.

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.