Skip to content

postgres: add --json body example to create-role help#5110

Closed
jamesbroadhead wants to merge 1 commit intodatabricks:mainfrom
jamesbroadhead:jb/postgres-create-role-help
Closed

postgres: add --json body example to create-role help#5110
jamesbroadhead wants to merge 1 commit intodatabricks:mainfrom
jamesbroadhead:jb/postgres-create-role-help

Conversation

@jamesbroadhead
Copy link
Copy Markdown

Summary

`databricks postgres create-role`'s `--json` flag binds to the inner `Role` object (`CreateRoleRequest.Role`, JSON-tagged `"role"`), so users must supply `spec` / `name` / etc. directly. Without an example this isn't obvious — the auto-generated help leaves the spec fields unflagged (`// TODO: complex arg: spec` in the generator), and the server's error when the body is wrong is vague:

```
Field 'role' is required and must contain at least one subfield with a non-default value
```

That fires whenever the inner `Role` has no recognized fields, which most commonly happens when a user wraps the body in `{"role": ...}` (matching the wire format the SDK marshals to). The CLI strips the unknown outer key with `Warning: unknown field: role` and ships an empty body. Walking out of that loop currently requires reading the SDK source.

This adds a curated override (`cmd/workspace/postgres/overrides.go`) that appends a concrete service-principal-role example to `cmd.Long`, plus a short note on the wrapping pitfall.

Help output (after)

```
Arguments:
PARENT: The Branch where this Role is created. Format:
projects/{project_id}/branches/{branch_id}

Body shape (passed via --json): fields go directly on the Role object.
Do not wrap them in '{"role": ...}' — the CLI will strip the unknown
outer key and the server will reject the empty body with "Field 'role'
is required".

Example — create a service-principal-backed role:

databricks postgres create-role projects/<PROJECT_ID>/branches/<BRANCH_ID> \
--role-id <SP_CLIENT_ID> \
--json '{"spec": {"identity_type": "SERVICE_PRINCIPAL", "postgres_role": "<SP_CLIENT_ID>", "auth_method": "LAKEBASE_OAUTH_V1", "membership_roles": ["DATABRICKS_SUPERUSER"]}}'
```

Scope

This PR only touches `create-role`. The same shape gap (`// TODO: complex arg: spec` + opaque error) exists for `create-endpoint`, `create-branch`, `create-project`, and `create-database`. Happy to extend if the approach is right; left them out so reviewers can decide on the pattern first.

Test plan

  • `go build ./cmd/workspace/postgres/...`
  • `databricks postgres create-role --help` shows the new section (output above)
  • `make fmt` clean
  • Reproduced the original confusion with a service-principal payload before the change; with this PR the example would have led me straight to the working body shape

This pull request and its description were written by Isaac.

`databricks postgres create-role`'s `--json` flag binds to the inner Role
object (CreateRoleRequest.Role, JSON-tagged "role"), so users supply
`spec`/`name`/etc. directly. Without an example this is non-obvious:

- Auto-generated help leaves `// TODO: complex arg: spec` with no flag
  hint, so the only way to set spec fields is through `--json`.
- If a user wraps the body in `{"role": ...}` (matching the wire format
  the SDK marshals to), the CLI strips `role` as unknown and ships an
  empty body. The server then returns a generic
  `Field 'role' is required and must contain at least one subfield with
  a non-default value` — which is hard to act on.

Adds a curated override that appends a concrete service-principal-role
example to `cmd.Long`, plus a short note on the wrapping pitfall.

Same pattern (auto-gen TODO `spec`/`status`, opaque error on bad body)
exists for create-endpoint, create-branch, create-project, and
create-database. Holding off on those until this approach is approved.

Co-authored-by: Isaac
@github-actions
Copy link
Copy Markdown

An authorized user can trigger integration tests manually by following the instructions below:

Trigger:
go/deco-tests-run/cli

Inputs:

  • PR number: 5110
  • Commit SHA: a64a9fa2e711494ce1d6901f732f3b9f1ee2e757

Checks will be approved automatically on success.

@github-actions
Copy link
Copy Markdown

Waiting for approval

Based on git history, these people are best suited to review:

  • @simonfaltum -- recent work in cmd/workspace/postgres/

Eligible reviewers: @andrewnester, @anton-107, @denik, @pietern, @renaudhartert-db, @shreyas-goenka

Suggestions based on git history. See OWNERS for ownership rules.

@jamesbroadhead
Copy link
Copy Markdown
Author

Superseded by #5111 (same branch, pushed to databricks/cli directly instead of from my fork).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant