Storage Service

sigMAX combines a Rust/Axum adapter for declared PostgreSQL operations with Studio tools for database administration, schema design and component proposals. Generated WASM handlers call logical bindings through the host; SQL, credentials and database connections remain outside business modules.

Storage is separate from the choice between Core and Pro. That distinction concerns deployment and the WASM execution boundary, not a restriction on particular storage backends. The adapter currently implemented here supports PostgreSQL.

What The Database Integration Provides

Capability	Current implementation
Application queries	Declared, parameterized reads, inserts and stored-procedure calls.
Multiple logical databases	A protected default database plus named databases inside the project namespace.
Database inspection	Public-schema tables and columns, primary keys, previews, views and stored routines.
Schema artifacts	Component initialization SQL, a database schema document and an entity-relationship diagram.
Assisted design	An AI-assisted schema proposal and generated initial SQL, with a separate apply action.
Sample data	AI-assisted row proposals for an existing table and generated insert SQL.
Components from data	An application-contract proposal built from selected table fields or reusable operations.

Runtime Flow

Declare — The contract declares a storage operation and its allowed runtime imports.
Bind — A route binding identifies the storage app, endpoint and required capability. Typed bindings also declare their input and output types.
Call — The WASM handler calls the logical operation through the host.
Authorize — The host resolves the binding, checks its declared capability and invokes the storage service through Dapr.
Execute — The adapter maps JSON input fields to SQL parameters and executes the configured operation.
Return — The host returns the result to the handler, which builds the public response.

The runtime supports both structured typed conversion and JSON service-invocation bindings. Neither exposes a direct database connection to the module. A result such as found: 0 can represent an absent record; the handler maps it to the HTTP behavior declared by its API contract.

Declared PostgreSQL Operations

The current sigmax.storage/v0.1 specification contains a PostgreSQL datasource and a list of operations.

Field	Meaning
`datasource.kind`	Must be `postgres` in the current implementation.
`datasource.env`	Environment variable containing the connection URL.
Operation `name` and `method`	Logical operation name and private POST endpoint.
`input_type`, `output_type`	Declared type names associated with the operation.
`database`	Optional logical database selection inside the configured namespace.
`query.kind`	`select_one`, `insert_one` or `call`.
`query.sql`, `query.params`	Parameterized SQL and mappings from `input.<field>`.
`query.not_found`	Required fallback output for a `select_one` that finds no row.

select_one returns the first result row or the declared fallback. It does not automatically add a SQL LIMIT, so the query itself should bound its work. insert_one requires INSERT ... RETURNING and one returned row. call executes a stored procedure and returns ok and affectedRows.

Parameter types are currently string, uuid, i64, i32 and bool. Missing fields fail; JSON null and empty strings are converted to SQL null. This conversion matters when designing nullable values and validation rules.

Operation SQL must match the declared operation shape, contain no semicolon and pass the adapter’s forbidden-keyword checks. There is no generic select_many, update or delete operation kind. A declared procedure can perform application-specific work, but its behavior must be reviewed as part of the database contract. These checks are not a general SQL parser or a substitute for database privileges.

Database Management And Inspection

The private adapter exposes the following administrative endpoints, all using POST:

Endpoint	Behavior
`/databases/list`	List databases belonging to the configured namespace.
`/databases/create`	Create a named UTF-8 database.
`/databases/delete`	Delete a named database, forcibly disconnecting existing sessions. The default is protected.
`/databases/contents`	Inspect public tables, column definitions and a preview of up to 50 rows per table.
`/databases/apply`	Apply supported initialization or seed SQL within a transaction.

Inspection also builds a reusable operation catalogue from public-schema views, functions and procedures. A catalogOnly request omits row previews and schema-file content. The current catalogue captures primary keys and nullability but does not reconstruct every constraint, index or relationship from an existing database.

Studio exposes project database management when the PostgreSQL extent is installed. Its topology starts PostgreSQL, the storage adapter and its Dapr sidecar on the private runtime network. Named database operations are administrative actions; a business route gains access only through its declared binding.

Schema Design, Seed Data And Components

Studio’s database workflow can start from a schema proposal or inspect an existing database.

Design — Describe the desired tables, columns and relationships. With a configured LLM, Studio produces a normalized proposal, SQL and an entity-relationship diagram.
Review & apply — Review the proposal and apply it to the selected database. Studio persists database/initialbase.sql, generated/database.schema.yaml and generated/database.er.mmd as project artifacts.
Seed — Optionally propose sample or seed rows for an existing table. The normalizer caps the draft at 500 rows per table, and the apply action stores database/generated-data.sql before execution.
Propose a component — Select table fields, queries or procedures to propose a component. The proposal includes public routes, private storage bindings and the chosen source database, and goes through the application-contract workflow.

The schema designer supports common PostgreSQL types, primary keys, nullability, unique columns and declared foreign-key relationships. The generated component references the existing schema with managed_schema: false; it is not an immediate publication of every database table.

The administrative SQL apply endpoint accepts at most 512 KiB and permits the supported forms of CREATE TABLE IF NOT EXISTS, foreign-key additions and generated literal-value inserts. It does not expose an unrestricted SQL console or create stored procedures. A reusable procedure must already exist in the database.

Artifacts are persisted before SQL application. If execution fails, the saved proposal can remain available; a generated SQL file alone is not evidence that its changes were applied successfully.

Migrations And Traceability

For components that declare managed entities, the artifact worker generates composant_<name>/migrations/<name>.init.sql, an aggregate schema document and an entity-relationship diagram. Studio lists those initialization files with their MinIO version identifiers and history.

This is traceable generation of initialization artifacts. It does not establish an automatic incremental migration, rollback or live schema reconciliation system. Review changes to SQL, parameter mappings, schema and output types alongside the contracts and validation reports.

Project artifact history and snapshots are described in Files and Object Storage. They preserve generated material; running database backups are a separate operational concern.

Configuration And Execution Boundary

Setting	Purpose
`SIGMAX_STORAGE_SPEC`	Specification path; defaults to `/app/generated/storage.yaml`.
Datasource environment variable	Holds the PostgreSQL connection URL; the topology uses `DATABASE_URL`.
`STORAGE_BIND`	Listener; defaults to `0.0.0.0:8090`.
`SIGMAX_DATABASE_NAME`	Logical database namespace; otherwise derived from the connection URL.

The adapter validates and loads the specification at startup. Generated POST endpoints are registered from that specification. Its /healthz returns a service response; it does not execute a fresh database health query.

The inspected adapter has no internal per-user authorization middleware and uses PostgreSQL connections without TLS. Its administrative endpoints therefore belong behind the controlled private service boundary. Host capability checks govern module calls, while service credentials and database permissions govern actual database access.

In the Pro architecture, COS2000 executes business WASM within KubeVirt VMs. Database access remains behind the host-controlled interface. The Rust storage service described here does not itself prove that the full COS2000-to-host database path is integrated.

Implementation References

Operation execution and administration are implemented in storage-service/src/main.rs. Host bindings are in runtime/src/primitives.rs. Studio’s database design and component proposal code is in studio/apps/api/src/services/database-ai.ts and studio/apps/api/src/routes/database.ts; artifact generation is in studio/apps/worker/src/stages.ts in the inspected sigMAX_runtime repository.

See the runtime capability catalogue for the other available services.