Zero to Database in One Command: SysMARA's New Init Pipeline

· SysMARA Team

Before v0.6.0, setting up a SysMARA project with a database required multiple manual steps: initialize the project, edit the config to add a database section, create a Docker compose file, write environment files, configure connection strings, and remember to add everything to .gitignore. Each step was small, but together they represented a significant barrier — especially for AI agents bootstrapping projects from a single prompt.

Starting with v0.6.0, all of this happens in one command.

The New Init Flow

mkdir my-project && cd my-project
npm init -y && npm install @sysmara/core
npx sysmara init --db postgresql --orm sysmara-orm

This single init command now creates everything you need:

  • YAML specs — starter entity, capability, policy, invariant, module, and flow files in system/
  • Config with database — sysmara.config.yaml pre-configured with your selected database provider and ORM adapter
  • Docker environment — docker-compose.yml with the correct database image (PostgreSQL 16, MySQL 8, or none for SQLite), health checks, volumes, and port mappings
  • Production Dockerfile — multi-stage Node.js build with non-root user
  • Environment files — .env.example (documented template) and .env.local (pre-filled with local dev connection string)
  • .gitignore — comprehensive rules for Node.js, SysMARA, environment secrets, and IDE files

Step by Step: From Zero to Running API

Here is the complete workflow from an empty directory to a running backend with a database:

Step 1: Initialize

mkdir task-manager && cd task-manager
npm init -y
npm install @sysmara/core
npx sysmara init --db postgresql --orm sysmara-orm

Choose your database: --db postgresql, --db mysql, or --db sqlite. Choose your ORM: --orm sysmara-orm, --orm prisma, --orm drizzle, or --orm typeorm. Both default to PostgreSQL and SysMARA ORM if omitted.

Step 2: Start the database

# Start PostgreSQL in Docker (skip for SQLite)
docker compose up -d

# Verify it's running
docker compose ps

The generated docker-compose.yml includes a health check, so the database container will report healthy when it's ready to accept connections.

Step 3: Write your specs

Edit the YAML files in system/ to define your domain. For a task manager: 

# system/entities.yaml
entities:
  - name: task
    description: A task in a project
    module: tasks
    fields:
      - name: id
        type: string
        required: true
      - name: title
        type: string
        required: true
      - name: status
        type: string
        required: true
      - name: assignee_id
        type: string
        required: false
      - name: created_at
        type: datetime
        required: true

Step 4: Build

npx sysmara build

The build pipeline now runs seven steps:

  1. Parse and validate all specs
  2. Cross-validate references
  3. Build system graph and system map
  4. Compile capabilities (route handlers, test scaffolds, metadata)
  5. Scaffold starter implementation files (entities, capabilities, policies, invariants, services)
  6. Generate database schema from entity specs
  7. Run diagnostics

Step 6 is new: the build pipeline automatically reads your entity specs and generates the SQL schema in app/database/. No separate sysmara db generate call needed.

Step 5: Apply the schema

# Apply the generated schema to your database
psql $DATABASE_URL -f app/database/sysmara-orm/schema.sql

Step 6: Implement and run

The scaffold generator has created typed starter files in app/. Edit them to implement your business logic, then start your server: 

node app/server.js

What the Docker Environment Looks Like

The generated docker-compose.yml for PostgreSQL: 

# Generated by SysMARA
services:
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: sysmara
      POSTGRES_PASSWORD: sysmara
      POSTGRES_DB: sysmara_dev
    ports:
      - "5432:5432"
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U sysmara"]
      interval: 5s
      timeout: 5s
      retries: 5

  app:
    build: .
    ports:
      - "3000:3000"
    env_file:
      - .env.local
    depends_on:
      db:
        condition: service_healthy

volumes:
  db_data:

For MySQL, the db service uses mysql:8 with the appropriate environment variables and health check. For SQLite, the db service is omitted entirely — the app service runs standalone with a file-based database.

Environment Files

Two environment files are generated:

.env.example — a documented template that goes into version control: 

# SysMARA Environment Variables
# Copy this file to .env.local and fill in real values.

DATABASE_URL=
PORT=3000
HOST=0.0.0.0
LOG_LEVEL=info
NODE_ENV=development

.env.local — pre-filled local defaults (gitignored): 

# Local development environment — DO NOT COMMIT
DATABASE_URL=postgresql://sysmara:sysmara@localhost:5432/sysmara_dev
PORT=3000
HOST=0.0.0.0
LOG_LEVEL=debug
NODE_ENV=development

The connection string matches the Docker compose database credentials. For production, copy .env.example and fill in real values.

Why This Matters for AI Agents

The entire point of SysMARA is that AI agents should be able to build backends from a prompt. Every manual step in the setup process is a step where the agent can get stuck, guess wrong, or produce inconsistent configuration.

With v0.6.0, the init-to-running path is:

  1. npx sysmara init --db postgresql — everything configured
  2. docker compose up -d — database running
  3. Write YAML specs
  4. sysmara build — schema generated, code scaffolded
  5. Implement handlers
  6. Start server

No manual config editing. No separate Docker setup. No environment file guessing. The BOOTSTRAP.md protocol has been updated to include these steps, so AI agents following the bootstrap protocol get database support automatically.

See the CLI Reference for full documentation on the new init flags, or the Quick Start for the updated step-by-step tutorial.