CLI Reference (`sgql`)¶

The db-graphql-gateway comes with a powerful command-line interface (sgql) designed to help you manage, inspect, and test your gateway configuration.

Global Options¶

--version: Show the version and exit.
--help: Show the help message and exit.

Commands¶

`sgql init`¶

Initialize a new db-graphql-gateway configuration file (sgql.yaml) in the current directory.

sgql init

This generates a default sgql.yaml configuring authentication, security limits, and pagination defaults.

`sgql inspect`¶

Inspect the live database schema and generate an Intermediate Representation (IR).

Options: - --dsn TEXT: Database connection string (or use DATABASE_URL environment variable).

sgql inspect --dsn postgresql://user:pass@localhost:5432/db

This command connects to the specified database (PostgreSQL, SQLite, or MySQL), introspects tables, views, and relationships, and outputs the detected schema statistics.

`sgql doctor`¶

Inspect system readiness and check dependencies for production deployment.

Options: - --dsn TEXT: Database connection string to test connectivity.

sgql doctor --dsn sqlite:///my_database.sqlite

Doctor checks: - Python environment version (Requires 3.10+) - Presence of required dependencies (asyncpg, jwt, strawberry) - Database reachability (if a DSN is provided) - Presence of the Gateway configuration file (sgql.yaml)

`sgql security`¶

Run a security audit against the current configuration and policy rules.

Options: - --config TEXT: Path to config file (default: sgql.yaml).

sgql security --config sgql.yaml

Verifies that JWT authentication, row-level authorization policies, AST maximum depth and alias limits, and production error masking are properly enabled.

`sgql validate`¶

Validate current configuration, IR definitions, and schema mappings.

Options: - --config TEXT: Path to config file (default: sgql.yaml).

sgql validate --config sgql.yaml

Parses the YAML configuration and validates it against the internal Pydantic schema model.

`sgql diff`¶

Show differences between the live database schema and the generated IR.

Options: - --dsn TEXT: Database connection string.

sgql diff --dsn mysql://root:pass@127.0.0.1:3306/db

Useful for detecting schema drift after running database migrations.

`sgql generate`¶

Generate GraphQL schema from IR and configuration.

sgql generate

Builds the GraphQL type definitions and wires up the DataLoader resolvers.

`sgql test`¶

Run generated GraphQL schema unit and integration tests.

sgql test

Executes the gateway test suite to ensure resolving logic operates safely.

Configuration Reference (`sgql.yaml`)¶

Below is a complete, fully annotated sgql.yaml configuration example demonstrating all supported fields, security limits, auth providers, and table/field mapping overrides:

# ==============================================================================
# db-graphql-gateway Configuration (sgql.yaml)
# ==============================================================================

# ------------------------------------------------------------------------------
# 1. Global Gateway Settings
# ------------------------------------------------------------------------------
# Opt-in exposure mode: when false, newly migrated tables/columns stay hidden
# until explicitly declared under `tables` below.
auto_expose: false

# Global ceiling for Relay-style cursor pagination (`first` / `last` arguments)
max_page_size: 100


# ------------------------------------------------------------------------------
# 2. Authentication Provider Settings
# ------------------------------------------------------------------------------
auth:
  enabled: true
  provider: jwt                 # Auth provider ("jwt" or custom provider)
  algorithms:
    - HS256
    - RS256
  secret_key: "${JWT_SECRET}"   # Supports environment variable substitution
  issuer: "https://auth.example.com"
  audience: "db-graphql-gateway"


# ------------------------------------------------------------------------------
# 3. Security & AST Complexity Hardening
# ------------------------------------------------------------------------------
security:
  # Maximum nesting depth allowed for queries (prevents recursive DoS attacks)
  max_depth: 5

  # Maximum number of field aliases allowed per query
  max_aliases: 15

  # Total query complexity point limit calculated at AST validation time
  max_complexity: 200

  # Production error masking: hides raw asyncpg/SQL tracebacks from clients
  error_masking: true

  # Lock down __schema introspection queries in production environments
  disable_introspection: false


# ------------------------------------------------------------------------------
# 4. Sensitive Field Automatic Redaction Patterns
# ------------------------------------------------------------------------------
# Any DB column matching these case-insensitive substrings will be automatically
# omitted from the GraphQL schema during introspection unless overridden below.
sensitive_field_patterns:
  - password
  - pwd
  - secret
  - token
  - hash
  - ssn
  - api_key
  - credit_card


# ------------------------------------------------------------------------------
# 5. Table & Column Granular Mapping / Whitelist
# ------------------------------------------------------------------------------
tables:
  # --- Example 1: Standard Exposed Table with Custom Field Names ---
  users:
    graphql_name: User          # Custom GraphQL Type Name (default: table name)
    hidden: false               # Expose this table in GraphQL schema

    fields:
      id:
        graphql_name: id
        hidden: false

      email:
        graphql_name: email
        hidden: false

      password_hash:
        hidden: true            # Force hide column even if explicitly requested

      created_at:
        graphql_name: createdAt # CamelCase alias for GraphQL client convention
        hidden: false

  # --- Example 2: Multi-tenant Organization Table ---
  organizations:
    graphql_name: Organization
    hidden: false

    fields:
      id:
        graphql_name: id
        hidden: false

      name:
        graphql_name: name
        hidden: false

      tenant_id:
        hidden: true            # Internal RLS column; used in SQL WHERE, hidden from GraphQL

  # --- Example 3: Internal / Sensitive Table (Completely Hidden) ---
  internal_audit_logs:
    hidden: true                # Hide entire table from GraphQL schema

CLI Reference (sgql)¶

Global Options¶

Commands¶

sgql init¶

sgql inspect¶

sgql doctor¶

sgql security¶

sgql validate¶

sgql diff¶

sgql generate¶

sgql test¶

Configuration Reference (sgql.yaml)¶