Database plugins

Database plugins run on the controller and connect to the selected database using DB-API compatible drivers. SQLite is built into Python. PostgreSQL, MySQL and Oracle drivers are optional extras.

pip install 'automax[postgres]'
pip install 'automax[mysql]'
pip install 'automax[oracle]'
pip install 'automax[database]'

All database plugins support DDL, DML and SELECT statements. They open a transaction, commit on success by default and roll back on failure. Autocommit is not enabled.

Common parameters:

connection: {}
query: "SELECT ..."          # one statement
statements: []               # or multiple statements
query_params: []             # DB driver parameters for the final statement
output: rows                 # rows, scalar, json, none
fetch: all                   # all, one, none
commit: true                 # false rolls back at the end intentionally

Secrets are resolved through the configured secret providers before rendering:

password: "{{ secrets.db_password }}"

database.sqlite.query

- id: create_table
  use: database.sqlite.query
  with:
    connection:
      path: /tmp/app.sqlite
    statements:
      - "CREATE TABLE IF NOT EXISTS app_config (key TEXT PRIMARY KEY, value TEXT)"
      - "INSERT OR REPLACE INTO app_config(key, value) VALUES ('version', '1.0.0')"
    output: none

- id: read_version
  use: database.sqlite.query
  with:
    connection:
      path: /tmp/app.sqlite
    query: "SELECT value FROM app_config WHERE key = ?"
    query_params: [version]
    output: scalar
    fetch: one
  register:
    database_version: data.scalar

database.postgres.query

Requires automax[postgres].

- id: postgres_query
  use: database.postgres.query
  with:
    connection:
      host: db01.example.com
      port: 5432
      database: appdb
      user: app
      password: "{{ secrets.postgres_password }}"
    query: "SELECT current_database() AS database_name"
    output: json

A DSN can also be used:

connection:
  dsn: "postgresql://app:{{ secrets.postgres_password }}@db01/appdb"

database.mysql.query

Requires automax[mysql].

- id: mysql_query
  use: database.mysql.query
  with:
    connection:
      host: db01.example.com
      port: 3306
      database: appdb
      user: app
      password: "{{ secrets.mysql_password }}"
    query: "SELECT VERSION() AS version"
    output: rows

database.oracle.query

Requires automax[oracle].

- id: oracle_query
  use: database.oracle.query
  with:
    connection:
      dsn: db01.example.com/FREEPDB1
      user: app
      password: "{{ secrets.oracle_password }}"
    query: "SELECT sysdate FROM dual"
    output: rows

Scaling to new databases

Add a new module under automax.plugins.db, subclass DatabaseQueryPlugin, and register the canonical plugin in build_builtin_registry() or load it through an external plugin path. The shared base already handles statement validation, output shaping and common result metadata.

Database smoke script

Use the controller-side smoke script for release or lab evidence:

scripts/database-smoke.sh --engine sqlite
scripts/database-smoke.sh --engine all

SQLite runs locally. PostgreSQL, MySQL/MariaDB and Oracle run when their environment variables are provided.

Database health checks

database.sqlite.check is a read-only controller-side health check plugin for the existing SQLite, PostgreSQL, MySQL/MariaDB and Oracle database families. It is intended for precheck and postcheck gates, not for application queries.

Example:

use: database.sqlite.check
with:
  engine: sqlite
  connection:
    path: /var/lib/app/app.sqlite
  checks: [connect, select, version, integrity]

Passwords are never rendered in manual commands; external database command examples use masked placeholders.