Namespaces - Temporal Go SDK feature guide

This page shows how to do the following:

You can create, update, deprecate, or delete your Namespaces using either the Temporal CLI or SDK APIs.

Use Namespaces to isolate your Workflow Executions according to your needs. For example, you can use Namespaces to match the development lifecycle by having separate dev and prod Namespaces. You could also use them to ensure Workflow Executions between different teams never communicate - such as ensuring that the teamA Namespace never impacts the teamB Namespace.

On Temporal Cloud, use the Temporal Cloud UI to create and manage a Namespace from the UI, or tcld commands to manage Namespaces from the command-line interface.

On self-hosted Temporal Service, you can register and manage your Namespaces using the Temporal CLI (recommended) or programmatically using APIs. Note that these APIs and Temporal CLI commands will not work with Temporal Cloud.

Use a custom Authorizer on your Frontend Service in the Temporal Service to set restrictions on who can create, update, or deprecate Namespaces.

You must register a Namespace with the Temporal Service before setting it in the Temporal Client.

How to register Namespaces

Registering a Namespace creates a Namespace on the Temporal Service or Temporal Cloud.

On Temporal Cloud, use the Temporal Cloud UI or tcld commands to create Namespaces.

On self-hosted Temporal Service, you can register your Namespaces using the Temporal CLI (recommended) or programmatically using APIs. Note that these APIs and Temporal CLI commands will not work with Temporal Cloud.

Use a custom Authorizer on your Frontend Service in the Temporal Service to set restrictions on who can create, update, or deprecate Namespaces.

Use Register API with the NamespaceClient interface to register a Namespace and set the Retention Period for the Workflow Execution Event History for the Namespace.

You can also register Namespaces using the Temporal CLI command-line tool.

client, err := client.NewNamespaceClient(client.Options{HostPort: ts.config.ServiceAddr})
        //...
    err = client.Register(ctx, &workflowservice.RegisterNamespaceRequest{
        Namespace: your-namespace-name,
        WorkflowExecutionRetentionPeriod: &retention,
    })

The Retention Period setting using WorkflowExecutionRetentionPeriod is mandatory. The minimum value you can set for this period is 1 day.

Once registered, set Namespace using Dial in a Workflow Client to run your Workflow Executions within that Namespace. See how to set Namespace in a Client in Go for details.

Note that Namespace registration using this API takes up to 10 seconds to complete. Ensure that you wait for this registration to complete before starting the Workflow Execution against the Namespace.

To update your Namespace, use the Update API with the NamespaceClient.

To update your Namespace using the Temporal CLI, use the temporal operator namespace update command.

How to manage Namespaces

You can get details for your Namespaces, update Namespace configuration, and deprecate or delete your Namespaces.

On Temporal Cloud, use the Temporal Cloud UI or tcld commands to manage Namespaces.

On self-hosted Temporal Service, you can manage your registered Namespaces using the Temporal CLI (recommended) or programmatically using APIs. Note that these APIs and Temporal CLI commands will not work with Temporal Cloud.

Use a custom Authorizer on your Frontend Service in the Temporal Service to set restrictions on who can create, update, or deprecate Namespaces.

You must register a Namespace with the Temporal Service before setting it in the Temporal Client.

On Temporal Cloud, use the Temporal Cloud UI or tcld commands to manage Namespaces.

Update information and configuration for a registered Namespace on your Temporal Service:

With the Temporal CLI: temporal operator namespace update Example

Use the UpdateNamespace API to update configuration on a Namespace. Example

//...
  err = client.Update(context.Background(), &workflowservice.UpdateNamespaceRequest{
  Namespace:         "your-namespace-name",
  UpdateInfo:        &namespace.UpdateNamespaceInfo{ //updates info for the namespace "your-namespace-name"
      Description:   "updated namespace description",
      OwnerEmail:    "newowner@mail.com",
      //Data:        nil,
      //State:       0,
  },
  /*other details that you can update:
  Config:            &namespace.NamespaceConfig{ //updates the configuration of the namespace with the following options
      //WorkflowExecutionRetentionTtl: nil,
      //BadBinaries:                   nil,
      //HistoryArchivalState:          0,
      //HistoryArchivalUri:            "",
      //VisibilityArchivalState:       0,
      //VisibilityArchivalUri:         "",
  },
  ReplicationConfig: &replication.NamespaceReplicationConfig{ //updates the replication configuration for the namespace
      //ActiveClusterName: "",
      //Clusters:          nil,
      //State:             0,
  },
  SecurityToken:     "",
  DeleteBadBinary:   "",
  PromoteNamespace:  false,
  })*/
//...

Get details for a registered Namespace on your Temporal Service:
- With the Temporal CLI: temporal operator namespace describe
- Use the DescribeNamespace API to return information and configuration details for a registered Namespace. Example
```
//...
  client, err := client.NewNamespaceClient(client.Options{})
  //...
  client.Describe(context.Background(), "default")
//...
```

Get details for all registered Namespaces on your Temporal Service:

With the Temporal CLI: temporal operator namespace list
Use the ListNamespace API to return information and configuration details for all registered Namespaces on your Temporal Service. Example

//...
    namespace.Handler.ListNamespaces(context.Context(), &workflowservice.ListNamespacesRequest{ //lists 1 page (1-100) of namespaces on the active Temporal Service. You can set a large PageSize or loop until NextPageToken is nil
        //PageSize:        0,
        //NextPageToken:   nil,
        //NamespaceFilter: nil,
        })
//...

Delete a Namespace: The DeleteNamespace API deletes a Namespace. Deleting a Namespace deletes all running and completed Workflow Executions on the Namespace, and removes them from the persistence store and the visibility store. Example:
```
//...
client.OperatorService().DeleteNamespace(ctx, &operatorservice.DeleteNamespaceRequest{...
//...
```

How to register Namespaces​

How to manage Namespaces​

How to register Namespaces

How to manage Namespaces