Database Explorer
The Database Explorer lets you connect external databases to the Auris console, browse their schemas, run SQL queries, and monitor connection health — all from the browser, without leaving the admin console.
Access it from the sidebar: Database Explorer with sub-sections Connections, Query Editor, Schema Browser, Data Viewer, Monitoring, and Actions.
Overview
Each Auris tenant maintains its own set of database connections. A connection stores the host, credentials (encrypted at rest), engine type, and optional SSH tunnel and pool configuration. Once a connection is saved and tested, you can:
- Browse tables, columns, indexes, and foreign keys in the Schema Browser
- Run arbitrary SQL in the Query Editor, save queries for reuse, and review execution history
- Page through table data in the Data Viewer with column visibility controls and CSV export
- Monitor active connections, database size, and slow queries in the Monitoring view
- Execute maintenance actions such as VACUUM, ANALYZE, and REINDEX from the Actions page
Adding a Connection
Open the Connections page
Navigate to Database Explorer → Connections. Click New Connection.
Fill in the connection details
| Field | Required | Notes |
|---|---|---|
| Name | Yes | Must be unique within your tenant |
| Engine | Yes | See supported engines below |
| Host | Yes | Hostname or IP address |
| Port | Yes | Default varies by engine |
| Database | Yes | Database name |
| Username | Yes | |
| Password | Yes | Stored encrypted; never shown after save |
| Connection String | No | Overrides host/port/database when provided |
| SSL | No | Toggle to enable TLS |
| SSL Mode | No | disable, require, verify-ca, or verify-full |
| Environment | No | development, staging, production, testing, or other |
| Tags | No | Free-form labels for filtering |
| Color | No | Visual indicator in the connections list |
| Read-only | No | Blocks any write or DDL statements |
| Vault Credential | No | Link to a stored Vault credential instead of entering a password |
| SSH Tunnel | No | Jump-host configuration for private networks |
| Pool Config | No | Connection pool size and timeout settings |
Test the connection
Click Test Connection before saving. The console sends a probe to the target host and reports the latency. The connection status is updated to online on success or error on failure.
Save
Click Save. The connection appears in the list with its current status badge.
Supported Database Engines
| Engine | Value |
|---|---|
| PostgreSQL | postgresql |
| MySQL | mysql |
| MariaDB | mariadb |
| MongoDB | mongodb |
| Redis | redis |
| SQLite | sqlite |
| Microsoft SQL Server | mssql |
| CockroachDB | cockroachdb |
| PlanetScale | planetscale |
| Supabase | supabase |
| Neon | neon |
| Elasticsearch | elasticsearch |
| ClickHouse | clickhouse |
| Turso | turso |
| Prisma | prisma |
Editing and Deleting Connections
From the connections list, click the row menu (three dots) to access View, Edit, Test, and Delete options. Deletion is a soft-delete — the connection is removed from all views but the record is retained for query history integrity.
Schema Browser
Navigate to Database Explorer → Schema Browser.
- Select a connection from the dropdown.
- Optionally select a schema (for engines that support multiple schemas, such as PostgreSQL). The default schema is
public. - Use the search box to filter tables by name.
The table list shows each table with its estimated row count and storage size. Click any row to expand it and load the table detail panel, which includes:
Columns
| Column | Description |
|---|---|
| Name | Column name |
| Type | Data type as reported by the database engine |
| Nullable | Whether the column accepts NULL |
| Default | Default value expression, if any |
| Primary Key | Marked if the column is part of the primary key |
Indexes
Each index shows its name, the columns it covers, whether it is unique, and the index type (B-tree, Hash, GIN, etc., depending on the engine).
Foreign Keys
Each foreign key shows the local column(s), the referenced table and column(s), and the ON DELETE / ON UPDATE actions.
The schema endpoint paginates at the table list level (up to 100 tables per page). Table detail (columns, indexes, foreign keys) is loaded separately when you expand a row.
Query Editor
Navigate to Database Explorer → Query Editor.
Running a Query
- Select a connection from the dropdown at the top. The first available connection is selected automatically.
- Enter SQL in the editor area.
- Press Ctrl+Enter or click Run to execute.
Results appear in the Results tab as a paginated table. Each cell value can be copied to the clipboard with a single click. The full result set can be downloaded as a CSV file.
If the result set is very large, a truncation warning appears above the table indicating that only a subset of rows is shown.
SQL execution errors are shown inline in the Results tab rather than as a dialog. A red error banner appears below the editor with the database error message. The HTTP request itself returns 200 — this is intentional so that the editor can display the error in context rather than triggering a generic error handler.
Queries are validated server-side before being sent to the database. Statements that fail validation (for example, obvious injection patterns) are rejected before reaching the connection.
Saved Queries
Click Save Query after writing a query. Enter a name and press Enter to confirm. Saved queries are associated with the current connection.
In the Saved tab:
- All saved queries for the active connection are listed with their names and descriptions.
- Click a row to load its SQL back into the editor.
- Shared queries (with the Shared badge) are visible to all users in the tenant with the
execute:db_queriespermission. - Hover over a row to reveal the delete button.
To mark a query as shared, use Edit from the saved queries list and toggle the Shared option.
Query History
The History tab lists all queries executed in the current session and recent past for the selected connection, in reverse chronological order. Each entry shows the SQL, execution time, row count, and status (success or error).
Click any history entry to reload its SQL into the editor.
History is scoped to your user and tenant. Other users’ query history is not visible. The list shows up to 200 entries.
Data Viewer
Navigate to Database Explorer → Data Viewer to browse the actual rows in a table without writing SQL.
- Select a connection.
- Click the table picker (a searchable popover). Filter by schema if needed, then select a table.
- The data grid loads the first page of rows.
Grid controls:
| Control | Description |
|---|---|
| Search | Full-text row search applied server-side |
| Sort | Click a column header to sort ascending, click again for descending, again to clear |
| Column visibility | Toggle which columns are shown via the Columns button |
| Copy cell | Click any cell to copy its value to the clipboard |
| CSV export | Download the current result set (all pages) as a CSV file |
| Pagination | Navigate pages; page size is configurable |
Monitoring
Navigate to Database Explorer → Monitoring.
Select a connection to view its live health data. The monitoring view shows four summary cards at the top:
| Card | Description |
|---|---|
| Active Connections | Number of currently open connections to the database server |
| Database Size | Total storage used by the selected database |
| Slow Queries | Number of queries that exceeded the slow-query threshold |
| Avg Latency | Average query latency from the last monitoring poll |
Below the cards, the Slow Queries list shows the individual slow query entries in descending order of execution time. The list is paginated at 10 per page.
The monitoring data refreshes automatically. You can also trigger a manual refresh.
Monitoring data is fetched from the database engine’s internal statistics views (for example, pg_stat_activity on PostgreSQL). Availability of individual metrics depends on the engine.
Actions
Navigate to Database Explorer → Actions to execute maintenance operations on a connected database.
- Select a connection.
- Browse or search the actions catalog. Actions are grouped by category (currently: Maintenance).
- Click an action to see its description. Destructive actions are visually flagged.
- Click Execute. A confirmation dialog appears before the action runs.
Available maintenance actions include: VACUUM, ANALYZE, REINDEX, CLUSTER, CHECK TABLE, OPTIMIZE TABLE, and similar engine-specific equivalents. The exact set of available actions depends on the connected engine.
Maintenance actions run directly against the connected database. Some operations (such as VACUUM FULL or REINDEX) can lock tables and impact application performance. Run them during low-traffic windows.
Access Control
The Database Explorer uses four distinct permissions. Assign them to admin roles from Users & Roles → Roles.
| Permission | What it grants |
|---|---|
view:db_connections | View the connections list and individual connection details. Test connections. Browse schema, data, stats, and monitoring. |
manage:db_connections | Create, edit, and delete connections. Requires view:db_connections. |
execute:db_queries | Run SQL in the Query Editor. Access query history. Create, edit, and delete saved queries. |
manage:db_actions | Execute maintenance actions (VACUUM, ANALYZE, REINDEX, etc.). |
A typical separation of responsibilities:
- Read-only DB analyst:
view:db_connections+execute:db_queries - DB administrator: all four permissions
- Ops / SRE:
view:db_connections+manage:db_actions(monitoring and maintenance without query access)
The execute:db_queries permission allows running arbitrary SQL against any connection the user can view, including write statements on connections that are not marked read-only. Grant it only to trusted administrators.
Read-Only Connections
When a connection is marked Read-only, the server blocks any statement that is not a read query, regardless of the user’s permissions. This is an additional safeguard for production databases. Enable it when adding production connections where accidental writes would be harmful.
Console Navigation
The Database Explorer sections are accessible from the left sidebar under the Database Explorer group:
| Sidebar entry | URL path |
|---|---|
| Connections | /db/connections |
| Query Editor | /db/query |
| Schema Browser | /db/schema |
| Data Viewer | /db/data |
| Monitoring | /db/monitoring |
| Actions | /db/actions |
API Reference
All Database Explorer endpoints are under /api/db/. They require a valid admin Bearer token and the appropriate permission.
Connections
| Method | Path | Permission | Description |
|---|---|---|---|
| GET | /api/db/connections | view:db_connections | List connections. Filter by search, engine, environment, status. |
| POST | /api/db/connections | manage:db_connections | Create a connection. |
| GET | /api/db/connections/:id | view:db_connections | Get a single connection. |
| PATCH | /api/db/connections/:id | manage:db_connections | Update a connection (partial). |
| DELETE | /api/db/connections/:id | manage:db_connections | Soft-delete a connection. |
| POST | /api/db/connections/:id/test | view:db_connections | Test connectivity. Updates status and latency. |
| POST | /api/db/connections/:id/query | execute:db_queries | Execute SQL. Body: { sql: string }. |
| GET | /api/db/connections/:id/schema | view:db_connections | List tables. Supports page, limit (max 100), search, schema. |
| GET | /api/db/connections/:id/schema/:table | view:db_connections | Get columns, indexes, and foreign keys for a table. Supports ?schema=. |
| POST | /api/db/connections/:id/data | view:db_connections | Paginated table rows. Body: { table, schema?, page?, limit?, search?, sortColumn?, sortDirection? }. |
| GET | /api/db/connections/:id/monitoring | view:db_connections | Active connections, database sizes, slow queries. |
| POST | /api/db/connections/:id/actions | manage:db_actions | Execute a maintenance action. Body: { action: string }. |
Query History
| Method | Path | Permission | Description |
|---|---|---|---|
| GET | /api/db/query-history | execute:db_queries | List history. Filter by connectionId. Max 200 entries. |
Saved Queries
| Method | Path | Permission | Description |
|---|---|---|---|
| GET | /api/db/saved-queries | execute:db_queries | List saved queries. Filter by connectionId. |
| POST | /api/db/saved-queries | execute:db_queries | Create a saved query. Body: { connectionId, name, sql, description?, isShared? }. |
| PATCH | /api/db/saved-queries/:id | execute:db_queries | Update a saved query. |
| DELETE | /api/db/saved-queries/:id | execute:db_queries | Delete a saved query. |
Stats
| Method | Path | Permission | Description |
|---|---|---|---|
| GET | /api/db/stats | view:db_connections | Overview counts (total/online/offline/error), engine breakdown, environment breakdown, saved query count, recent history. |