Create Databases

Create Database

POST /v1/databases

Create a managed MariaDB database in the active account. It starts as provisioning; ngris creates it on the shared database server within seconds and it becomes ready (poll GET /v1/databases/{uuid}). Its name inside MariaDB is generated, app_ + the name in lowercase letters, digits and _ + _ + 8 generated characters, and never changes.

Every new database gets a first, read-write user: app, unless you pass initial_user_name. The response carries that user's password once: ngris stores it encrypted and the API never returns it again. Apps you connect as the user get it automatically; if you lose it, rotate the password.

Requires Databases write and a plan with managed databases. The database counts against the plan's limit (Team 3, Enterprise 10).

Request body

name string

Required. Your label: 1–64 characters, no control characters, unique in the account (surrounding spaces are trimmed).

initial_user_name string

Optional. The first user's name, default app: 1–32 characters, no control characters, not starting with _.

engine string

Optional. mariadb, the only engine.

Response (201 Created)

database object

The new database (database object), status: "provisioning".

user object

The first user (user object), read-write, status: "provisioning".

password string

The user's password, 48 hex characters. Shown only in this response.

password_notice string

A reminder that the password is shown only once.

Errors

400

invalid request body, engine must be mariadb, Database name must be 1-64 characters, with no control characters, or User name must be 1-32 characters, with no control characters, not starting with _.

403

No Databases write, no active account, Managed databases are not available on your plan, or the plan's limit is reached: You've reached your plan's limit of 3 managed databases — delete one or upgrade your plan.

409

name_taken: A database with this name already exists.

503

databases_unavailable, or Another managed database change is in progress — please retry.

Request
curl -X POST "https://api.ngris.com/v1/databases" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "orders-db" }'

Response — 201 Created
{
  "database": {
    "uuid": "019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18",
    "name": "orders-db",
    "engine": "mariadb",
    "status": "provisioning",
    "placement": "shared",
    "db_name": "app_orders_db_k3x9q2tm",
    "host": "mariadb-apps.ngris-appdb.svc.cluster.local",
    "port": 3306,
    "size_bytes": null,
    "size_measured_at": null,
    "quota_paused": false,
    "connected_app_count": 0,
    "user_count": 1,
    "created_at": "2026-10-18T09:00:00Z",
    "updated_at": "2026-10-18T09:00:00Z"
  },
  "user": {
    "uuid": "019c2a41-7d40-7e15-9b63-2f8c4d1a7e95",
    "name": "app",
    "db_user": "u_p7d2m1_app",
    "access": "read_write",
    "kind": "customer",
    "status": "provisioning",
    "created_at": "2026-10-18T09:00:00Z",
    "updated_at": "2026-10-18T09:00:00Z",
    "database_uuid": "019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18",
    "used_by": []
  },
  "password": "<48 hex characters, shown once>",
  "password_notice": "This password is shown only once. ngris stores it encrypted and never shows it again — rotate the user's password if you lose it."
}

Response — 403 (plan limit)
{
  "error": "You've reached your plan's limit of 3 managed databases — delete one or upgrade your plan"
}

PreviousList & Get NextRename Database

On this page

Create Database