Docs

Reference

CLI Reference

The DBA SaaS CLI provides full control over your agents, pools, and metrics from the command line. It is the fastest way to manage your infrastructure without leaving the terminal.

Installation

Install the CLI globally via npm:

npm install -g @dbasaas/cli

Verify the installation:

dbasaas --version

Authentication

Log in to your DBA SaaS account:

dbasaas login

This opens a browser window for OAuth authentication. After approval, your credentials are stored in ~/.dbasaas/config.yaml. For CI/CD environments, use an API key instead:

dbasaas login --api-key YOUR_API_KEY

Commands

  • dbasaas agents list — list all registered agents and their status (online, offline, degraded)
  • dbasaas agents add — register a new agent. Returns an agent ID and connection token for the agent configuration file
  • dbasaas pools create — create a new agent pool. Pools group agents by environment, team, or region
  • dbasaas issues list — list all active issues detected across your agents. Supports filters: --severity critical|warning|info, --pool POOL_NAME
  • dbasaas metrics query — query collected metrics. Supports time ranges (--from, --to), agent filters (--agent), and metric names (--metric)

Configuration File

The CLI stores configuration at ~/.dbasaas/config.yaml. This file contains:

  • api_endpoint — API base URL (default: https://api.dbasaas.com/v1)
  • auth_token — your authentication token (managed by dbasaas login)
  • default_pool — optional default pool for commands that accept a --pool flag
  • output_format — output format: table (default), json, or yaml

Agent Configuration

The DBA SaaS agent runs alongside your PostgreSQL instance and collects performance metrics, query statistics, and system-level data.

Configuration File

The agent reads its configuration from /etc/dbasaas/agent.yaml. A minimal configuration requires only the connection string and API key:

  • connection_string — PostgreSQL connection URI (e.g., postgresql://dbasaas@localhost:5432/mydb)
  • api_key — agent API key obtained from the dashboard or CLI
  • agent_id — unique agent identifier assigned during registration

Key Settings

  • pool — name of the agent pool this agent belongs to
  • collection_interval — how often metrics are collected, in seconds (default: 60)
  • query_stats_interval — how often query statistics are sampled (default: 300)
  • tls.enabled — enable TLS for agent-to-cloud communication (default: true)
  • tls.ca_cert — path to a custom CA certificate, if using a private CA
  • tls.skip_verify — disable certificate verification (not recommended for production)
  • log_level — logging verbosity: debug, info, warn, error (default: info)
  • log_file — path to the log file (default: /var/log/dbasaas/agent.log)

Environment Variables

All configuration settings can be overridden with environment variables. These take precedence over the config file:

  • DBASAAS_API_KEY — agent API key
  • DBASAAS_AGENT_ID — agent identifier
  • DBASAAS_ENDPOINT — API endpoint URL (overrides api_endpoint)
  • DBASAAS_CONNECTION_STRING — PostgreSQL connection string
  • DBASAAS_COLLECTION_INTERVAL — metric collection interval in seconds
  • DBASAAS_LOG_LEVEL — logging verbosity

API Overview

The DBA SaaS REST API provides programmatic access to all platform features. Use it to integrate DBA SaaS into your existing tooling, dashboards, and automation workflows.

Base URL

https://api.dbasaas.com/v1

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Generate API tokens from the dashboard under Settings or via the CLI with dbasaas token create.

Key Endpoints

  • GET /agents — list all agents with their status, last seen time, and assigned pool
  • GET /agents/:id — get detailed information about a specific agent
  • GET /pools — list all agent pools and their member counts
  • GET /pools/:id — get pool details including agent list and aggregate metrics
  • GET /metrics — query time-series metrics. Supports query parameters: agent_id, metric, from, to, interval
  • GET /issues — list detected issues. Supports filters: severity, status, agent_id, pool_id
  • GET /issues/:id — get issue details including AI-generated recommendations

Rate Limits

API rate limits vary by plan:

  • Free — 100 requests per minute
  • Pro — 1,000 requests per minute
  • Enterprise — unlimited

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. When the limit is exceeded, the API returns a 429 Too Many Requests response.