Database Schema

The command_log table

The command_log table stores traced command executions.

Schema

create table command
(
    id                 bigint generated by default as identity (start with 1),
    tenant_id          text,
    user_id            text,
    cmd_uuid           uuid    not null,
    cmd_source_ref     text,
    cmd_class          text,
    cmd_version        text                     default 'v1',
    state              text    not null,
    dry_run            boolean,
    attributes         jsonb,
    importance         text,
    retention          text,

    http_method        text,
    http_status        text,
    http_status_code   smallint,

    problem_code       text,
    problem            jsonb,

    cmd_body           jsonb,

    created_at         timestamp with time zone default now(),
    started_at         timestamp with time zone,
    ended_at           timestamp with time zone,
    duration_in_millis integer,
    protected_at       timestamp with time zone,
    archived_at        timestamp with time zone,

    version            integer not null         default 0,
    constraint pk_command primary key (id)
);

Column reference

id: Auto-generated primary key.
tenant_id: Tenant scope. Populated from TenantIdAware.getTenantId().
user_id: User scope. Populated from UserIdAware.getUserId().
cmd_uuid: Unique command identifier (required). Generated by the tracing interceptor.
cmd_source_ref: Optional reference to the originating source (e.g., a correlation ID or external request ID).
cmd_class: Fully qualified class name of the command (e.g., com.example.order.CreateOrderCommand).
cmd_version: Defaults to v1.
state: Execution outcome. Values: Created, Cancelled, Successful, Rejected, Conflict, Failed.

Derived from HTTP status: 2xx → Successful, 3xx → Cancelled, 4xx → Rejected, 5xx → Failed.
dry_run: true if the command implements DryRunEnabled and was executed in dry-run mode.
attributes: JSONB map of custom key-value pairs from AttributesEnabled.attributes().
importance: Low, Normal, or High. Controls query filtering and retention policy.
retention: ShortLived, LongLived, or Permanent. Derived from importance: Low → ShortLived, Normal → LongLived, High → Permanent.
http_method: HTTP method of the request (GET, POST, PUT, DELETE, PATCH).
http_status: HTTP status name (e.g., OK, BAD_REQUEST).
http_status_code: Numeric HTTP status code (e.g., 200, 400, 500).
problem_code: Application-specific error code from the Problem response body.
problem: Full Problem response body as JSONB.
cmd_body: Command payload as JSONB. Excluded when CommandTracingOption.ExcludeCmdBody is set.
created_at: Timestamp when the row was inserted (defaults to now()).
started_at: Timestamp when command execution started.
ended_at: Timestamp when command execution completed.
duration_in_millis: Execution duration in milliseconds.
protected_at: Optional timestamp for retention protection.
archived_at: Optional timestamp marking the command as archived.

Installing migrations

The conta-command-postgresql module ships Flyway migrations as resources. To use them in your project, extract them into your own migrations directory using the no.conta.archive-extract Gradle plugin.

Gradle setup

Add the plugin to your db module (the module that applies java-library and owns your migrations). The extracted SQL files are placed in src/main/resources and become part of the published jar, so downstream modules that depend on your db module get the migrations automatically.

plugins {
    id 'no.conta.archive-extract'
}

archiveExtract {
    commandMigrations {
        from "no.conta.command:conta-command-postgresql:${contaCommandVersion}" as String
        include 'migrations/*.sql'
        files {
            rename 'migrations/V001__create_table_command.sql', 'V1_0_0_010__create_table_command.sql'
            rename 'migrations/V002__rename_table_command_to_command_log.sql', 'V1_0_0_011__rename_table_command_to_command_log.sql'
            rename 'migrations/V003__create_helper_functions.sql', 'V1_0_0_012__create_helper_functions.sql'
        }
        into 'src/main/resources/com/example/migrations'
    }
}

Rename each upstream migration to match your project’s Flyway versioning scheme. This ensures the command log migrations run in the right order relative to your own migrations.

Every matched file must have a rename or skip entry. When you upgrade the library and a new migration is added, the build fails until you explicitly handle it — no migration is silently included or ignored.

Skipping migrations

If a migration is not needed (e.g., you created the table manually or the helper functions are not wanted), use skip instead of rename:

archiveExtract {
    commandMigrations {
        from "no.conta.command:conta-command-postgresql:${contaCommandVersion}" as String
        include 'migrations/*.sql'
        files {
            rename 'migrations/V001__create_table_command.sql', 'V1_0_0_010__create_table_command.sql'
            rename 'migrations/V002__rename_table_command_to_command_log.sql', 'V1_0_0_011__rename_table_command_to_command_log.sql'
            skip 'migrations/V003__create_helper_functions.sql'
        }
        into 'src/main/resources/com/example/migrations'
    }
}