> ## Documentation Index
> Fetch the complete documentation index at: https://openworkflow.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Namespaces

> Isolate environments with namespace IDs

Namespaces let you run multiple isolated environments in the same database. For
example, you can use one database for both staging and production by giving each
environment a different namespace. Workflows in one namespace are completely
invisible to another.

## How Namespaces Work

Every workflow run and step attempt is tagged with a `namespaceId`. Workers and
clients only see data in their namespace.

```ts theme={null}
import { BackendPostgres } from "openworkflow/postgres";

// Production namespace
const prodBackend = await BackendPostgres.connect(url, {
  namespaceId: "production",
});

// Staging namespace (same database)
const stagingBackend = await BackendPostgres.connect(url, {
  namespaceId: "staging",
});
```

## Default Namespace

If you don't specify a `namespaceId`, the default is `"default"`:

```ts theme={null}
// These are equivalent
const backend = await BackendPostgres.connect(url);
const backend = await BackendPostgres.connect(url, { namespaceId: "default" });
```

## Use Cases

### Environment Isolation

Run development, staging, and production in the same database:

```ts theme={null}
import { defineConfig } from "@openworkflow/cli";
import { BackendPostgres } from "openworkflow/postgres";

const namespace = process.env.OPENWORKFLOW_NAMESPACE_ID || "development";

export default defineConfig({
  backend: await BackendPostgres.connect(
    process.env.OPENWORKFLOW_POSTGRES_URL!,
    {
      namespaceId: namespace,
    },
  ),
});
```

Set the namespace per environment:

<CodeGroup>
  ```bash npm theme={null}
  # Development
  OPENWORKFLOW_NAMESPACE_ID=development npm run worker
  # Staging
  OPENWORKFLOW_NAMESPACE_ID=staging npm run worker
  # Production
  OPENWORKFLOW_NAMESPACE_ID=production npm run worker
  ```

  ```bash pnpm theme={null}
  # Development
  OPENWORKFLOW_NAMESPACE_ID=development pnpm run worker
  # Staging
  OPENWORKFLOW_NAMESPACE_ID=staging pnpm run worker
  # Production
  OPENWORKFLOW_NAMESPACE_ID=production pnpm run worker
  ```

  ```bash bun theme={null}
  # Development
  OPENWORKFLOW_NAMESPACE_ID=development bun run worker
  # Staging
  OPENWORKFLOW_NAMESPACE_ID=staging bun run worker
  # Production
  OPENWORKFLOW_NAMESPACE_ID=production bun run worker
  ```
</CodeGroup>

### Multi-Tenancy

Isolate workflows per tenant:

```ts theme={null}
async function getBackendForTenant(tenantId: string) {
  return BackendPostgres.connect(process.env.OPENWORKFLOW_POSTGRES_URL!, {
    namespaceId: `tenant-${tenantId}`,
  });
}
```

### Testing

Use separate namespaces for test runs:

```ts theme={null}
// In your test setup
const testNamespace = `test-${Date.now()}`;

const backend = await BackendPostgres.connect(testUrl, {
  namespaceId: testNamespace,
});
```

## SQLite Namespaces

Namespaces work the same way with SQLite:

```ts theme={null}
import { BackendSqlite } from "openworkflow/sqlite";

const backend = BackendSqlite.connect("./backend.db", {
  namespaceId: "development",
});
```

## Data Visibility

Each namespace is completely isolated:

| Namespace    | Can See                     |
| ------------ | --------------------------- |
| `production` | Only `production` workflows |
| `staging`    | Only `staging` workflows    |
| `default`    | Only `default` workflows    |

A worker with `namespaceId: "production"` will never pick up work from the
`staging` namespace.

## Dashboard

The dashboard shows workflows for the namespace configured in your config file.
To view a different namespace, update the config and restart the dashboard.

## Best Practices

1. **Use environment variables** - Don't hardcode namespace IDs
2. **Consistent naming** - Use clear names like `production`, `staging`,
   `development`
3. **One namespace per worker pool** - Don't mix namespaces in the same worker
   process
4. **Clean up test namespaces** - Periodically remove old test data