Skip to content

Environment Protection

Environment protection restricts who can run SQLMesh commands against specific environments from their local development machine. When a protection is active, only users on the exception list for that environment can connect to it through the dagctl CLI.

How It Works

Protection is environment-name based and scoped to your organization. You define a protection record for an environment name (e.g., prod, staging) and then control which users are excepted from the restriction.

  • No protection configured - Any project member can target the environment from the CLI.
  • Protection enabled - Only users explicitly added to the exception list can target that environment from the CLI. All other users are blocked.
  • Protection disabled (toggled off) - The protection record exists but is not applied. All users can target the environment until it is re-enabled.

This is an allowlist model: you protect an environment, then add specific users who are permitted to run against it.

Where protection applies

Protection is evaluated by the dagctl CLI when it establishes a state database connection — that is, when a developer runs SQLMesh locally against a dagctl-managed project. It is enforced by get_state_connection(), which every CLI-generated config.py calls, and it fails closed if the API cannot be reached.

Protection is a control over local developer access to an environment. It is separate from the permissions that govern who can approve and execute plans in the web UI — those are role-based and configured under Organizations. Use both together: protection for local access, and the approve_plan permission for deployments.

Configuring Protection

Navigate to Settings → Secrets, then the Protection tab.

Warning

Viewing and changing protection records requires the manage_secrets permission, held by the Owner, Admin, and Developer roles. Organization owners have it by default.

The Protection tab itself is shown to anyone with view_secrets, which includes Readers — but a Reader opening it will not be able to load or modify any protection records.

Adding a Protection

  1. Click Add Protection.
  2. Enter the environment name exactly as it appears in your project configuration (e.g., prod).
  3. Leave Enabled toggled on if you want the protection active immediately.
  4. Click Add Protection.

The protection is now active. No users are excepted yet - add them next.

Adding Excepted Users

Users on the exception list can connect to the protected environment from the CLI.

  1. Click the users icon next to the protection record.
  2. Select a user from the dropdown and click the add button.
  3. Repeat for each user who should have access.

To remove a user, click the delete icon next to their name in the exception list.

Toggling Protection On or Off

Use the toggle switch next to any protection record to enable or disable it without deleting the record or changing the exception list. This is useful for temporarily opening an environment for maintenance without losing your access configuration.

Deleting a Protection

Click the delete icon and confirm. This removes the protection entirely. All users can target the environment until a new protection is added.

Supported Frameworks

Environment protection is evaluated by the dagctl CLI, which is used with SQLMesh projects. dbt projects are managed entirely through the web UI and do not establish CLI state connections, so protection records do not apply to them.

The environment name must match what your project configuration uses as the target environment.

Key Takeaways

  • ✅ Protection is an allowlist: add a protection, then add the users who are permitted
  • ✅ Users not on the exception list are blocked from connecting to that environment via the CLI
  • ✅ Protection governs local developer access; plan approval is governed separately by role permissions
  • ✅ Protection records are organization-scoped, not per-project
  • ✅ Toggle protection off temporarily without losing your exception list
  • ✅ Environment names are matched exactly - prod and Prod are different
  • ✅ The Protection tab lives under Settings → Secrets; managing records requires manage_secrets