> ## Documentation Index
> Fetch the complete documentation index at: https://docs.insforge.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and Execute Database Migration



## OpenAPI

````yaml https://raw.githubusercontent.com/InsForge/InsForge/main/openapi/tables.yaml post /api/database/migrations
openapi: 3.0.3
info:
  title: Insforge Tables API
  version: 1.0.0
servers: []
security: []
paths:
  /api/database/migrations:
    post:
      tags:
        - Admin
      summary: Create and Execute Database Migration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - version
                - name
                - sql
              properties:
                version:
                  type: string
                  description: >-
                    Numeric migration version. Accepts Drizzle-style sequential
                    prefixes (e.g. `0001`) or a `YYYYMMDDHHmmss` timestamp.
                    Versions are compared numerically.
                  pattern: ^\d{1,64}$
                  maxLength: 64
                name:
                  type: string
                  description: Migration name
                  minLength: 1
                sql:
                  type: string
                  description: SQL text to parse and execute immediately
                  minLength: 1
            example:
              version: '20260416170500'
              name: create_posts_table
              sql: >-
                CREATE TABLE posts (id UUID PRIMARY KEY DEFAULT
                gen_random_uuid(), title TEXT NOT NULL);
      responses:
        '201':
          description: Migration executed and recorded successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Migration'
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
              example:
                version: '20260416170500'
                name: create_posts_table
                statements:
                  - >-
                    CREATE TABLE posts (id UUID PRIMARY KEY DEFAULT
                    gen_random_uuid(), title TEXT NOT NULL);
                createdAt: '2026-04-16T17:05:00.000Z'
                message: Migration executed successfully
        '400':
          description: Invalid migration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidPayload:
                  value:
                    error: INVALID_INPUT
                    message: 'sql: Migration SQL is required'
                    statusCode: 400
                transactionStatement:
                  value:
                    error: DATABASE_FORBIDDEN
                    message: Custom migrations cannot manage their own transactions.
                    statusCode: 400
        '409':
          description: >-
            Migration version already exists or is not newer than the latest
            applied migration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: ALREADY_EXISTS
                message: Migration version already exists.
                statusCode: 409
      security:
        - bearerAuth: []
        - apiKey: []
components:
  schemas:
    Migration:
      type: object
      required:
        - version
        - name
        - statements
        - createdAt
      properties:
        version:
          type: string
          pattern: ^\d{1,64}$
        name:
          type: string
        statements:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      required:
        - error
        - message
        - statusCode
      properties:
        error:
          type: string
          description: Error code for programmatic handling
        message:
          type: string
          description: Human-readable error message
        statusCode:
          type: integer
          description: HTTP status code
        nextActions:
          type: string
          description: Suggested action to resolve the error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

````