Skip to main content

How to Configure Stateless & Database-Free Boot Mode

This guide explains how to configure and run Framework M in a completely Stateless & Database-Free Mode.

By decoupling the framework from a mandatory database, you can deploy ultra-lightweight, high-speed applications suited for edge microservices, serverless functions, real-time calculators, event-driven workers, and command-line tools.

Because database adapters are lazy-loaded, you can entirely omit installing heavy dependencies like SQLAlchemy or asyncpg to keep your container and serverless footprints incredibly small.

1. Enabling Stateless Mode​

To boot Framework M without any database engines or persistent disk connections, set the DATABASE_URL environment variable or container configuration to "none" (or omit it entirely):

# In your app-level .env or deployment environment:
DATABASE_URL=none

What happens behind the scenes:​

  1. Engine Bypass: The InitEngine bootstrap step skips creating a SQLAlchemy connection pool or binding active engines. Instead, it registers a lightweight NullEngine placeholder.
  2. Migration Bypass: The schema sync (m migrate sync) and migration patches runner (m migrate run) gracefully no-op when database connectivity is disabled.
  3. Instant Boot: Cold-start latency drops significantly as the app does not perform stateful handshakes, making it ideal for scale-to-zero architectures.

2. Health & Readiness Probes in Stateless Deployments​

If you are deploying a stateless container to Kubernetes or an orchestrator, the application's liveness and readiness endpoints adapt automatically:

  • Liveness Probe (GET /health): Skips database connectivity pings and verifies the status of other configured services (like NATS or Redis) to determine overall liveness.
  • Readiness Probe (GET /ready): Detects that the database is deliberately disabled. Instead of throwing a 503 Service Unavailable or waiting for pending migrations, it immediately returns 200 OK with: 
    {
      "status": "ready",
      "database": "disabled"
    }
    This ensures your stateless containers boot instantly and start receiving traffic without getting stuck in restart loops.

When running database-free, you can leverage Framework M’s modular hexagonal architecture to build highly powerful application roles:

A. Pure Event-Driven Workers (NATS / MQTT)​

You can consume events from a queue and perform real-time business calculations or dispatch downstream actions without local persistence:

  • Set DATABASE_URL=none.
  • Configure InMemoryEventBus or standard NatsEventBusAdapter for high-throughput messaging. (Note: Ensure you install the required messaging extra, e.g., uv add "framework-m-standard[nats]").

B. Stateless API Gateways & Security Proxies​

Use the framework as a stateless gatekeeper to authorize incoming requests:

  • Token Authentication: Use pluggable authentication strategies (OIDC / OAuth / JWT key validators) to verify incoming JWT signatures and extract scopes fully in-memory with zero local database lookups.
  • ABAC Policies: Authorize access on-the-fly using Framework M's declarative permission engine, matching token attributes against resource constraints.

C. Custom/API-Backed Repositories​

If a DocType is required for API exposure but gets its data from an upstream service rather than a local table:

  1. Turn off database mapping for the DocType: 
    class RemoteCustomer(DocType):
        class Meta:
            create_schema = False  # Skip local DB creation
  2. Implement a custom repository that satisfies the RepositoryProtocol to forward CRUD requests to an upstream microservice via gRPC or REST.

4. CLI Application Development​

Stateless mode is the ultimate runtime environment for CLI tools. Because the framework starts in milliseconds with zero stateful dependencies, you get:

  • Instant-launch utility commands.
  • Access to Pydantic-powered DocType validations, secrets parsing, logging formats, and dependency injection (container.py).
  • Perfect reusability of your core business logic and validators directly inside local shell commands.