# NEXUS AI SQL Safety Rules

Every SQL statement sent through NEXUS AI (managed database queries and external database intelligence) is checked before it runs. This page lists what passes.

## One statement per request

Multiple statements separated by `;` are rejected with `Multi-statement SQL is not allowed`. Semicolons inside quoted strings and dollar-quoted function bodies are fine.

## Allowed

| Class | Statements |
|---|---|
| Read | `SELECT`, `EXPLAIN` |
| Write (DML) | `INSERT`, `UPDATE`, `DELETE` |
| Schema (DDL) | `CREATE`, `ALTER`, `DROP TABLE`; `CREATE`, `DROP INDEX`; `CREATE`, `DROP VIEW`; `CREATE`, `DROP FUNCTION` and `PROCEDURE`; `CREATE`, `DROP TRIGGER`; `TRUNCATE` |

`UPDATE` and `DELETE` must include a `WHERE` clause.

## Blocked

These fail with `Query blocked: Statement type not permitted` or `Blocked operation detected`:

- `CREATE DATABASE`, `DROP DATABASE`
- `GRANT`, `REVOKE`, `CREATE ROLE`, `ALTER ROLE`
- `CREATE EXTENSION`, `CREATE SCHEMA`
- `COPY ... PROGRAM`, `pg_read_file`, `pg_write_file`, `pg_ls_dir`, `SHUTDOWN`
- Anything else not in the allowed table

## Alternatives when a statement is blocked

- Need another database: create a new managed database with `nexusai_managed_db_create` or `nexus managed-db create`.
- Need unrestricted access: get credentials with `nexusai_managed_db_connection` (audit-logged) and connect with `psql` or `mysql`. Confirm with the user first.

## Permissions

- Managed databases: reads need `managed_databases.read` (MCP scope `managed_db:read`); writes and DDL need `managed_databases.manage` (`managed_db:manage`). `nexusai_managed_db_query` is read-only; use `nexusai_managed_db_execute` for writes.
- External sources: `nexusai_db_query_preview` runs `EXPLAIN` for reads and shows the plan for writes. DML and DDL through `nexusai_db_query_execute` need `confirmed: true`. Results are capped at 1,000 rows with a 5 second statement timeout by default.
- Managed database queries time out after 30 seconds.

## Examples

```bash
nexus managed-db query shop "SELECT id, email FROM users LIMIT 10"
nexus managed-db query shop "CREATE TABLE notes (id serial PRIMARY KEY, body text NOT NULL)"
nexus managed-db query shop "UPDATE notes SET body = 'hi' WHERE id = 1"
```

Always quote the SQL in a shell.

## Related resources

- [Managed databases](/docs/managed-databases.md)
- [Database intelligence](/docs/db-intelligence.md)