postgres: add --json body example to create-role help#5110
Closed
jamesbroadhead wants to merge 1 commit intodatabricks:mainfrom
Closed
postgres: add --json body example to create-role help#5110jamesbroadhead wants to merge 1 commit intodatabricks:mainfrom
--json body example to create-role help#5110jamesbroadhead wants to merge 1 commit intodatabricks:mainfrom
Conversation
`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
|
An authorized user can trigger integration tests manually by following the instructions below: Trigger: Inputs:
Checks will be approved automatically on success. |
Waiting for approvalBased on git history, these people are best suited to review:
Eligible reviewers: Suggestions based on git history. See OWNERS for ownership rules. |
3 tasks
Author
|
Superseded by #5111 (same branch, pushed to databricks/cli directly instead of from my fork). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
This pull request and its description were written by Isaac.