EN Databases and Migrations

SQL databases and schema lifecycle

English · Türkçe · Languages / Diller

Scope: JSON API Forge 0.5.1 · Source review: 17 September 2026 · Language: English

Forge uses SQLAlchemy's asynchronous engine layer. A database alias selects the physical connection; a resource describes its HTTP contract. A project can have multiple aliases. Reusing an alias name in another project does not imply that both projects use the same connection.

System	URL driver	Use
SQLite	sqlite+aiosqlite:///./data/app.db	Local development and suitable small deployments
PostgreSQL	postgresql+asyncpg://…	Primary production integration target
MySQL/MariaDB	mysql+asyncmy://…	Asyncmy connection
MongoDB	URI under mongo_databases	Separate document-resource model

Load the entire connection URL from an environment variable instead of embedding credentials:

{
  "databases": {
    "primary": {
      "url": "$env:APP_DATABASE_URL",
      "support_schema_mode": "validate",
      "pool_pre_ping": true,
      "pool_size": 10,
      "max_overflow": 20,
      "pool_timeout": 30,
      "pool_recycle": 1800
    }
  }
}

This example assumes the database schema is already prepared. Encode special characters according to the driver's URL rules. Verify TLS and pooling settings against the database provider's connection contract.

Three schema responsibilities

Area	Contents	Operational control
Internal metadata database	API keys, management accounts, collaboration and audit/media metadata	INTERNAL_DATABASE_URL, INTERNAL_SCHEMA_MODE
Project business database	Application tables and operation support structures	databases.<alias>
Production migrations	Columns/indexes, data transformation and backward compatibility	Application-owned migration process

SQL operation idempotency records live in the business database and commit in the same transaction as the protected side effects. Moving the record to a separate metadata database would not preserve that atomicity.

From development to production

1. Start with explicit columns and auto_create: true where appropriate for development.
2. Back up schema and data, then test restoration.
3. Rehearse changes in a separate staging database.
4. Use forge migrate to prepare Forge support objects and declared auto-create tables.
5. Set INTERNAL_SCHEMA_MODE=validate and project support_schema_mode=validate.
6. Version long-lived business-schema changes through Alembic or a separate SQL migration process. Restrict the runtime role's DDL permissions accordingly.

auto_create does not transform an existing table into a new column layout. forge migrate does not maintain a complete migration history. Rolling back code does not automatically roll back transformed data.

Pooling and capacity

Budget connections across all workers, projects and aliases. Each worker can create multiple engines, each potentially using pool_size + max_overflow connections. Budget the internal database pool separately. These pool settings do not apply identically to SQLite. Investigate query plans, indexes and lock waits before simply increasing the pool size.

All fields: SQL and MongoDB model reference.

Sources and verification

This page describes the behavior at the pinned commits below. Recheck these contracts when upgrading.

• main/framework/db.py
• main/framework/config.py
• main/framework/cli.py
• main/docs/30-Database-Schema-Lifecycle-and-Migrations.md

---

English home · All English pages · Version maintenance