Guardrails Configuration

Create and manage pattern-based rules to block dangerous queries

Guardrails use pattern matching to evaluate queries and block dangerous operations before they execute. This page covers configuration options and rule syntax.

For an introduction to what Guardrails do and common use cases, see Guardrails Overview.

---

Creating a Guardrail

1. Navigate to Guardrails

   Go to Manage > Guardrails in the sidebar

2. Create New Guardrail

   Click Create New Guardrail in the top-right corner

3. Set Basic Information

   • Name: A short identifier (e.g., block-ddl, read-only-mode)
   • Description: Explain what this guardrail protects against
4. Add Rules

   Configure Input Rules and/or Output Rules (see below)

5. Assign Connections

   Select which connections this guardrail applies to

6. Save

   Click Save to activate the guardrail

---

Rule Configuration

Input Rules

Input rules evaluate queries before they execute. Use these to block dangerous commands.

Field	Description	Example
Pattern	Regex pattern to match	(?i)DROP\s+TABLE
Action	What to do when pattern matches	Block, Warn, Require Approval
Message	Error message shown to user	DDL commands are blocked

Output Rules

Output rules evaluate query results after execution. Use these to filter or redact output.

Field	Description	Example
Pattern	Regex pattern to match in output	\b\d{3}-\d{2}-\d{4}\b (SSN)
Action	What to do when pattern matches	Redact, Block, Warn
Replacement	Text to replace matches with	[REDACTED]

For data masking that automatically detects PII, see Live Data Masking instead.

---

Pattern Syntax

Guardrails use regular expressions (regex) for pattern matching. Here are the most useful patterns:

Basic Syntax

Syntax	Meaning	Example
(?i)	Case-insensitive	(?i)drop matches DROP, Drop, drop
\s+	One or more whitespace	DROP\s+TABLE matches DROP TABLE
\s*	Zero or more whitespace	DROP\s*TABLE matches DROPTABLE too
\b	Word boundary	\bDROP\b won’t match BACKDROP
^	Start of string	^SELECT only matches SELECT at start
$	End of string	;\s*$ matches trailing semicolon
.*	Any characters	SELECT.*FROM matches anything between
(?!...)	Negative lookahead	(?!.*WHERE) means “not followed by WHERE”

Common Patterns

Block UPDATE without WHERE:

(?i)^\s*UPDATE\s+\w+\s+SET\s+(?!.*WHERE)

Block DELETE without WHERE:

(?i)^\s*DELETE\s+FROM\s+\w+(?!.*WHERE)

Block all DDL:

(?i)^\s*(DROP|CREATE|ALTER|TRUNCATE)\s+(TABLE|DATABASE|INDEX|SCHEMA|VIEW)

Block SELECT * on specific tables:

(?i)SELECT\s+\*\s+FROM\s+(users|orders|transactions)

Require LIMIT clause:

(?i)SELECT\s+(?!.*\bLIMIT\b).*FROM

Testing Patterns

Before deploying a pattern, test it at regex101.com:

1. Select Flavor: ECMAScript (JavaScript)
2. Paste your pattern in the Regular Expression field
3. Enter test queries in the Test String field
4. Verify matches highlight correctly

---

Actions

Block

Prevents the query from executing and returns an error.

Use when: The operation should never be allowed (e.g., DROP TABLE in production)

User sees:

Error: Guardrail violation
Rule: block-ddl
Message: DDL commands are blocked in production

Warn

Allows the query but shows a warning message.

Use when: You want to educate users without blocking work (e.g., missing LIMIT)

User sees:

Warning: Consider adding a LIMIT clause to prevent large result sets
Query executed successfully.

Require Approval

Blocks the query until an approver approves it.

Use when: Some queries need human review before execution (e.g., bulk updates)

User sees:

This query requires approval.
Waiting for approval at https://use.hoop.dev/access-requests/abc123...

Require Approval uses the same workflow as Action Access Requests.

---

Connection Assignment

Each guardrail can be assigned to multiple connections. You can also have multiple guardrails on a single connection.

Assignment Options

Option	Description
Specific connections	Select individual connections from the list
All connections	Apply to every connection in your organization
Connection tags	Apply to connections matching specific tags

Evaluation Order

When multiple guardrails apply to a connection, they are evaluated in order of priority:

1. Priority 1 (highest) evaluated first
2. First matching rule determines the action
3. If no rules match, query is allowed

To set priority:

1. Go to Manage > Guardrails
2. Drag guardrails to reorder them
3. Higher position = higher priority

---

Environment Variables

These environment variables affect guardrails behavior on the gateway:

Variable	Description	Default
GUARDRAILS_ENABLED	Enable/disable guardrails globally	true
GUARDRAILS_LOG_LEVEL	Logging verbosity (debug, info, warn)	info

---

Monitoring Guardrails

Viewing Blocked Queries

1. Go to Sessions in the sidebar
2. Filter by Status: Blocked
3. Click a session to see details

Each blocked session shows:

• The query that was blocked
• Which guardrail and rule triggered
• The error message
• User and timestamp

Audit Log

All guardrail evaluations are logged:

• Blocked queries - Logged with full query text
• Warnings - Logged with warning message
• Approval requests - Logged with request status

Access audit logs in Sessions or export via the API.

---

Best Practices

Start with Warn

Use Warn mode first to understand impact before blocking

Test in Dev First

Apply guardrails to test connections before production

Be Specific

Use precise patterns to avoid false positives

Document Rules

Write clear descriptions explaining why each rule exists

Pattern Guidelines

1. Always use (?i) for case-insensitive matching
2. Use \b for word boundaries to avoid partial matches
3. Use ^\s* to allow leading whitespace
4. Test edge cases like multi-line queries and comments
5. Keep patterns simple - complex regex is hard to maintain

---

Troubleshooting

Pattern Not Matching

Check:

1. Test the pattern at regex101.com with the exact query
2. Verify case sensitivity (add (?i) if needed)
3. Check for leading/trailing whitespace in the query

Too Many False Positives

Fix:

1. Make the pattern more specific
2. Add word boundaries (\b)
3. Use negative lookahead for exceptions

Example: Pattern DROP blocks DROP_SHIPPED_ITEMS table name

Fix: (?i)^\s*DROP\s+(TABLE|DATABASE) only matches DDL commands

Performance Issues

If queries are slow:

1. Reduce the number of rules per connection
2. Simplify complex regex patterns
3. Avoid patterns with excessive backtracking (e.g., .*.*.*)

---

Related

Guardrails Overview

Learn what guardrails do and see common recipes

Live Data Masking

Configure automatic PII detection and masking

Action Access Requests

Configure the “Require Approval” action

Access Control

Control who can access which connections