MD_UPDATE_DIVE_STATUS

Sets the status of an existing Dive. The status is recorded against a specific version of the Dive; later content updates don't change it.

Syntax

SELECT * FROM MD_UPDATE_DIVE_STATUS(
  id ='your-dive-uuid'::UUID,
  status ='ready'
);

Parameters

Parameter	Type	Required	Description
id	UUID	Yes	The unique identifier of the Dive
status	VARCHAR	Yes	One of draft, ready, endorsed, or archived
version	UINTEGER	No	The reviewed version the status applies to. Defaults to the Dive's current version.

Permissions

🔒Requires permissionRoles and access control →

Update organization-wide Dive statusesAdmin ✓Builder —Explorer —

Marked preset roles include the permission by default; a custom role qualifies when it inherits a role that includes it. Owners can set draft, ready, or archived on their own Dives without this permission. Any status on any Dive, including endorsed, requires it.

Return columns

Returns the updated Dive summary.

Column	Type	Description
id	UUID	Unique identifier of the Dive
title	VARCHAR	Dive title
description	VARCHAR	Dive description
owner_id	UUID	UUID of the Dive owner
current_version	INTEGER	Latest version number (1-based)
created_at	TIMESTAMP WITH TIME ZONE	When the Dive was created
updated_at	TIMESTAMP WITH TIME ZONE	When the Dive was last updated
owner_name	VARCHAR	Name of the Dive owner
status	VARCHAR	The Dive's status
status_changed_at	TIMESTAMP WITH TIME ZONE	When the status was last set
status_set_by	UUID	UUID of the user who set the status
status_applies_to_version	UINTEGER	The version the status was set against

Examples

Mark a Dive as ready for others to use:

SELECT id, title, status, status_applies_to_version
FROM MD_UPDATE_DIVE_STATUS(
  id ='a1b2c3d4-e5f6-7890-abcd-ef1234567890'::UUID,
  status ='ready'
);

Endorse a specific reviewed version. This requires permission to update organization-wide Dive statuses:

SELECT *
FROM MD_UPDATE_DIVE_STATUS(
  id ='a1b2c3d4-e5f6-7890-abcd-ef1234567890'::UUID,
  status ='endorsed',
  version =3
);

Errors

• Returns an error if the Dive does not exist or you don't own it and don't have permission to update organization-wide Dive statuses.
• Returns an error if status isn't one of the four valid values.
• Returns an authorization error if you set endorsed without permission to update organization-wide Dive statuses.
• Returns an error if version doesn't exist for the Dive.

Related

• Dive statuses — What each status means and where it appears
• MD_LIST_DIVES — List Dives, including their statuses
• MD_GET_DIVE — Read a Dive, including its status