Update to Postman

{
  "description": "Use when creating or repairing dataset manifests, or when a collection needs queried or joined test inputs, a reusable named view, spreadsheet worksheet data, live database rows, or script access through pm.datasets(). Chooses between a simple iteration file and a dataset while preserving query semantics, portability, and credential boundaries. Use for requests such as \"run this collection over database rows\".",
  "included_files": [
    {
      "relative_path": "reference/schema.md",
      "size_in_bytes": 1868
    },
    {
      "relative_path": "reference/spreadsheets.md",
      "size_in_bytes": 1523
    }
  ],
  "name": "datasets",
  "skill_md_contents": "---\nname: datasets\ndescription: Use when creating or repairing dataset manifests, or when a collection needs queried or joined test inputs, a reusable named view, spreadsheet worksheet data, live database rows, or script access through pm.datasets(). Chooses between a simple iteration file and a dataset while preserving query semantics, portability, and credential boundaries. Use for requests such as \"run this collection over database rows\".\n---\n\n# Datasets\n\nA dataset gives files and database sources a queryable interface; a saved view\nturns the query into reusable test input. That is useful when filtering,\njoining, or refreshing rows is part of the test. A one-off CSV/JSON run can\nstay with `collection run -d`; a dataset should earn its extra configuration.\n\n## Choose the data and execution path\n\n1. Prefer local file sources for reproducible fixtures. A live database is\n   useful when current data is the point, but adds authentication, entitlement,\n   network, and credential requirements even in a local `.dataset.yaml`.\n   Check `postman dataset <action> -h` and the actual source capability before\n   promising a workflow; source support can vary with the installed CLI.\n2. Use the default federated SQLite query path to join supported sources.\n   `--source <name>` instead sends SQL to one source in its native dialect.\n   Switching modes to silence a SQL error changes query semantics. JDBC\n   requires the native path and cannot join in the federated layer; native\n   database connectors can support federation.\n3. Choose credentials before choosing a database connector. JDBC variables\n   and properties accept shared-vault references such as\n   `vault:<vaultId>/<secretId>`, resolved at query time. Native database\n   credentials are stored literally in dataset configuration on the documented\n   CLI surface; inspect current support before use, and keep secret-bearing\n   configuration out of Git. Literal values passed through stdin avoid argv\n   exposure but can still be persisted in YAML. See **variables** for vault\n   handling. A connector that enables a join may have a worse credential\n   boundary than JDBC; do not hide that tradeoff.\n4. Choose iteration or script access deliberately. The paired\n   `--iteration-data-dataset <path-or-id>` and\n   `--iteration-data-view <name-or-id>` flags feed one row per collection\n   iteration, with columns exposed as variables. They exclude `-d` and require\n   a parameter-free view because the runner has no query-parameter input.\n   Repeatable `--dataset <path-or-dir>` instead exposes `pm.datasets()` to\n   scripts; it does not itself create row-driven iterations.\n\n## Build a portable, queryable artifact\n\nCreate a local manifest with `postman dataset create <path.dataset.yaml>\n--name <name>`, then attach sources with `dataset source add`. Source commands\nsupply IDs and validation that hand-written entries can miss. When inspecting\nor repairing manifest fields, consult [Dataset YAML](reference/schema.md).\nExisting-dataset commands accept a local path or workspace ID; `list` needs a local path for\nlocal discovery, while workspace create/list use `--workspace`.\n\nFile sources are copied into `data_dir` unless `--ref-only` is used. That option\nrecords absolute paths and makes the dataset machine-specific. For a workspace\ndataset, adding `--file` alone registers a local filesystem source; `--upload`\nis what uploads bytes. Datasets are pushed along with the workspace; there is\nno separate `dataset push`.\n\nFor spreadsheet sources, use the worksheet-aware guidance in\n[Spreadsheet sources](reference/spreadsheets.md). For ordinary source names,\nprefer normalized identifiers: table names lowercase, collapse repeated\nunderscores, and strip edge underscores. A source called `users` is queried\nas `users`, not `source_users`. Verify actual tables before interpreting an\nunknown-table error as missing data.\n\nFor JDBC, `dataset jdbc inspect <driver.jar>` supplies driver class, URL\ntemplate, variables, and properties for `source add`; `--from-source` can reuse\na connection. JDBC addition tests connectivity unless disabled; native source\naddition needs a separate `dataset source test`. This distinction prevents\nmistaking a saved source for a working connection.\n\nProve the query with `dataset query` before saving it with `dataset view create`,\nthen run the view. Query parameters are positional (`$1`, `$2`, with `-p`\nvalues in order). Commit the manifest and intended source files; keep engine\nstate such as `data.db`, `meta.db`, `daemon.log`, and caches out of the repo.\nDataset commands do not create a `.postman/resources.yaml` registry entry.\nDeletion removes the manifest but preserves source files that may be shared.\nDeleting a workspace dataset is permanent; establish that intent rather than\ntreating deletion as a way to repair a query.\n\n## Interpret failures and results\n\nA generic server-error wrapper can hide SQL or connection errors. Use structured\n`--json` errors and their remediation, or `--debug` when necessary, to identify\nthe layer before retrying. `source test` separates database connectivity from\nSQL errors; file/URL sources have no connection to test. Engine startup failures\nmay need `data_dir`'s daemon log rather than a different query.\n\nScript dataset access is lazy, and invalid YAML can be skipped with a warning\nrather than failing the run. On a hosted collection, `--dataset` is not an\naccess-control boundary: scripts can access other datasets readable by the\nsession. Inspect the collection's data access before running untrusted scripts\nwith that session.\n\n## Verification\n\nReport the queried columns and row count, local/workspace location, live versus\ncopied sources, and federated versus native execution. For iteration runs,\ncompare the actual iteration count with the intended view rows and configured\nlimits. Matching counts establishes wiring, not that the data covers every\nbehavior the test needs. Creating a manifest alone proves neither.\n"
}