> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cubehosting.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Criar um banco de dados
> Crie um PostgreSQL, MySQL ou Redis na rede da sua conta.
Mande o tipo (`engine`), o nome e a memória. O nome é também o **endereço interno** que os seus projetos usam: um banco `loja-db` responde em `loja-db:5432` para os projetos da sua conta, e nenhum projeto de outra conta alcança. A senha é gerada pela Cube; pegue a conexão pronta em [Ver a conexão](/api-reference/databases/credentials).
Bancos vêm a partir do plano **Stack** (Stack 1, Tower 3, Fortress 6) e a memória sai do plano, junto com a dos projetos: no mínimo 512 MB, ou 256 MB no Redis. Cada banco tem 2 GB de espaço.
## Erros comuns
| Código | HTTP | O que fazer |
| ------------------------------------------------------------------ | ---- | --------------------------------------------------------------------------- |
| [`database_not_allowed`](/errors#param-database-not-allowed) | 403 | Mude para o Stack ou maior: o Free e o Block não têm bancos. |
| [`database_limit_reached`](/errors#param-database-limit-reached) | 403 | Exclua um banco que não usa ou mude de plano. |
| [`invalid_database_name`](/errors#param-invalid-database-name) | 400 | Use de 3 a 32 caracteres: minúsculas, números e hífen, começando com letra. |
| [`invalid_memory`](/errors#param-invalid-memory) | 400 | Respeite o mínimo do tipo (`minMemoryMb`) e a memória do plano. |
| [`database_name_taken`](/errors#param-database-name-taken) | 409 | Escolha outro nome: ele não repete na conta. |
| [`engine_unavailable`](/errors#param-engine-unavailable) | 409 | Escolha `postgres`, `mysql` ou `redis`: o MongoDB chega em breve. |
| [`insufficient_memory`](/errors#param-insufficient-memory) | 422 | Diminua `memoryMb`, libere memória de um projeto ou mude de plano. |
| [`account_suspended`](/errors#param-account-suspended) | 409 | Pague a renovação em Plano e cobrança. |
| [`insufficient_permission`](/errors#param-insufficient-permission) | 403 | Use uma chave de leitura e escrita. |
Todos os códigos, com o formato do erro, em [Códigos de erro](/errors).
## OpenAPI
````yaml POST /databases
openapi: 3.1.0
info:
title: API da Cube Hosting
version: 1.0.0
description: >-
Hospede bots de Discord, sites e APIs em Node.js e Python: envie o .zip,
inicie, pare, reinicie, leia logs e métricas, cuide das variáveis de
ambiente, faça e baixe backups, volte para uma versão anterior, crie bancos
de dados (PostgreSQL, MySQL, MongoDB e Redis), guarde arquivos privados no
Blob e veja o uso do plano. Para agentes de IA, o servidor MCP da conta
(`POST https://app.cubehosting.com.br/api/mcp`, JSON-RPC, com a mesma chave)
está em https://docs.cubehosting.com.br/account-mcp.
contact:
name: Cube Hosting
url: https://discord.gg/pv6D9tUsDV
servers:
- url: https://app.cubehosting.com.br/api
security:
- bearerAuth: []
tags:
- name: Projetos
- name: Controle
- name: Logs e métricas
- name: Variáveis de ambiente
- name: Backups
- name: Versões dos envios
- name: Bancos de dados
- name: Blob
- name: Avisos
- name: Conta
paths:
/databases:
post:
tags:
- Bancos de dados
summary: Criar um banco de dados
description: >-
Cria um PostgreSQL 17, MySQL 8.4 ou Redis 8 na rede da sua conta, a
partir do plano Stack (o MongoDB chega em breve: hoje, `mongodb`
responde `409 engine_unavailable`). O `name` é também o endereço interno
que os seus projetos usam (`loja-db:5432`): de 3 a 32 caracteres, letras
minúsculas, números e hífen, começando com letra, único na conta. A
memória sai da mesma memória do plano que a dos projetos (mínimo de 512
MB, ou 256 MB no Redis). A senha é gerada pela Cube; veja-a em [Ver a
conexão](/api-reference/databases/credentials). A resposta chega com o
banco já subindo (`starting`); em alguns segundos ele fica `running`.
operationId: createDatabase
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseInput'
example:
engine: postgres
name: loja-db
memoryMb: 512
responses:
'201':
description: Banco criado.
content:
application/json:
schema:
type: object
required:
- database
properties:
database:
$ref: '#/components/schemas/Database'
example:
database:
id: 01J9A2C4E6G8J0K2M4P6R8T0V2
name: loja-db
engine: postgres
engineName: PostgreSQL
host: loja-db
port: 5432
status: starting
memoryMb: 512
usage:
memoryMb: 18
disk:
usedMb: 39
limitMb: 2048
externalAccess:
isAvailable: true
isEnabled: false
host: db.cubehost.dev
certificate: null
startedAt: '2026-09-28T12:26:03.000Z'
createdAt: '2026-09-28T12:26:00.000Z'
updatedAt: '2026-09-28T12:26:01.000Z'
'400':
description: O corpo, o nome ou a memória não valem.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_request:
summary: invalid_request
value:
status: error
code: invalid_request
message: >-
Envie { "engine": "postgres" | "mysql" | "redis", "name":
"…", "memoryMb": 512 }.
invalid_database_name:
summary: invalid_database_name
value:
status: error
code: invalid_database_name
message: >-
O nome precisa ter de 3 a 32 caracteres: letras minúsculas
sem acento, números e hífen, começando com letra e sem
terminar em hífen (ex.: "loja-db"). Ele é o endereço que
os projetos usam para conectar.
field: name
invalid_memory:
summary: invalid_memory
value:
status: error
code: invalid_memory
message: >-
O PostgreSQL precisa de pelo menos 512 MB e cabe no máximo
nos 2048 MB do plano.
field: memoryMb
minMemoryMb: 512
'401':
description: Chave ausente, inválida ou revogada.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_api_key:
summary: invalid_api_key
value:
status: error
code: invalid_api_key
message: >-
Chave de API inválida ou revogada. Confira o cabeçalho
"Authorization: Bearer " ou crie outra em Chaves de
API no painel.
'403':
description: >-
A chave é só de leitura, ou o plano não tem (ou não comporta mais)
bancos.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
insufficient_permission:
summary: insufficient_permission
value:
status: error
code: insufficient_permission
message: >-
Esta chave é só de leitura. Para enviar, iniciar, parar,
reiniciar, mexer nas variáveis, fazer e baixar backups,
baixar e voltar versões dos envios, criar, ligar, desligar
e ver a senha dos bancos de dados ou enviar e apagar
arquivos do Blob, crie uma chave de leitura e escrita no
painel.
database_not_allowed:
summary: database_not_allowed
value:
status: error
code: database_not_allowed
message: >-
O plano Block não inclui bancos de dados. Eles vêm a
partir do Stack: mude de plano em Plano e cobrança.
database_limit_reached:
summary: database_limit_reached
value:
status: error
code: database_limit_reached
message: >-
O plano Stack permite até 1 banco de dados. Exclua um
banco ou mude de plano.
limit: 1
'409':
description: >-
O tipo de banco ainda chega em breve (o MongoDB), já existe um banco
com esse nome na conta, ou a conta está suspensa.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
engine_unavailable:
summary: engine_unavailable
value:
status: error
code: engine_unavailable
message: >-
O MongoDB chega em breve. Por enquanto, crie um
PostgreSQL, MySQL ou Redis.
field: engine
database_name_taken:
summary: database_name_taken
value:
status: error
code: database_name_taken
message: >-
Você já tem um banco chamado "loja-db". Escolha outro
nome.
field: name
account_suspended:
summary: account_suspended
value:
status: error
code: account_suspended
message: >-
Sua conta está suspensa porque o Pix da renovação não foi
pago, então os projetos ficam parados. Pague em Plano e
cobrança: a conta volta na hora, e o que estava no ar sobe
sozinho.
beta_ending:
summary: beta_ending
value:
status: error
code: beta_ending
message: >-
Seu beta terminou e a conta está voltando ao plano Free.
Espere alguns minutos e tente de novo.
'422':
description: >-
A memória pedida passa do que sobra no plano, somando projetos e
bancos.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
insufficient_memory:
summary: insufficient_memory
value:
status: error
code: insufficient_memory
message: >-
O banco pede 1024 MB, mas o plano Stack só tem 512 MB
livres somando projetos e bancos. Diminua a memória,
reduza ou exclua um projeto, ou mude de plano.
freeMemoryMb: 512
requestedMemoryMb: 1024
'429':
description: Limite de pedidos. Traz o cabeçalho `Retry-After`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
rate_limit_exceeded:
summary: rate_limit_exceeded
value:
status: error
code: rate_limit_exceeded
message: >-
A sua conta passou do limite da API do plano Free: 10
pedidos por minuto. Espere 42 s e tente de novo.
too_many_attempts:
summary: too_many_attempts
value:
status: error
code: too_many_attempts
message: Muitas tentativas. Tente de novo em 15 minutos.
'503':
description: O servidor dos bancos não respondeu. Nada foi criado.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
server_unavailable:
summary: server_unavailable
value:
status: error
code: server_unavailable
message: >-
O servidor dos projetos não respondeu. Tente de novo em
instantes.
x-codeSamples:
- lang: bash
label: curl
source: |-
curl -X POST https://app.cubehosting.com.br/api/databases \
-H "Authorization: Bearer $CUBE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"engine": "postgres", "name": "loja-db", "memoryMb": 512}'
- lang: javascript
label: Node.js
source: >-
const API = 'https://app.cubehosting.com.br/api';
const headers = { Authorization: `Bearer
${process.env.CUBE_API_KEY}` };
const res = await fetch(`${API}/databases`, {
method: 'POST',
headers: { ...headers, 'Content-Type': 'application/json' },
body: JSON.stringify({ engine: 'postgres', name: 'loja-db', memoryMb: 512 }),
});
const { database } = await res.json();
console.log(database.id, database.status); // starting
- lang: python
label: Python
source: |-
import os
import requests
API = "https://app.cubehosting.com.br/api"
headers = {"Authorization": f"Bearer {os.environ['CUBE_API_KEY']}"}
r = requests.post(
f"{API}/databases",
headers=headers,
json={"engine": "postgres", "name": "loja-db", "memoryMb": 512},
timeout=300,
)
r.raise_for_status()
print(r.json()["database"]["id"])
components:
schemas:
DatabaseInput:
type: object
required:
- engine
- name
- memoryMb
additionalProperties: false
properties:
engine:
type: string
enum:
- postgres
- mysql
- mongodb
- redis
description: '`mongodb` chega em breve: hoje responde `409 engine_unavailable`.'
name:
type: string
pattern: ^[a-z][a-z0-9-]{1,30}[a-z0-9]$
description: >-
De 3 a 32 caracteres: minúsculas, números e hífen, começando com
letra e sem terminar em hífen. Não pode ser `localhost` nem começar
com `cube`. Único na conta.
memoryMb:
type: integer
minimum: 256
description: Mínimo de 512 MB (256 MB no Redis), até a memória do plano.
Database:
type: object
description: 'Um banco de dados da conta: PostgreSQL, MySQL, MongoDB ou Redis.'
required:
- id
- name
- engine
- engineName
- host
- port
- status
- memoryMb
- usage
- disk
- externalAccess
- startedAt
- createdAt
- updatedAt
properties:
id:
type: string
description: ID do banco, 26 caracteres.
name:
type: string
pattern: ^[a-z][a-z0-9-]{1,30}[a-z0-9]$
description: Nome do banco, que é também o endereço interno.
engine:
type: string
enum:
- postgres
- mysql
- mongodb
- redis
engineName:
type: string
description: '`PostgreSQL`, `MySQL`, `MongoDB` ou `Redis`.'
host:
type: string
description: >-
O endereço que os projetos da conta usam (igual ao `name`). Só vale
de dentro da conta.
port:
type: integer
description: 5432 (PostgreSQL), 3306 (MySQL), 27017 (MongoDB) ou 6379 (Redis).
status:
type: string
enum:
- creating
- starting
- running
- restarting
- restoring
- stopped
- error
description: >-
`starting`: subiu e ainda não aceita conexões. `restoring`: um
backup está sendo restaurado. `error`: deveria estar no ar e não
está (a Cube tenta subir de novo a cada 30 s).
memoryMb:
type: integer
description: Memória reservada no plano.
usage:
oneOf:
- type: object
required:
- memoryMb
properties:
memoryMb:
type: integer
- type: 'null'
description: A memória em uso agora. `null` parado ou quando não dá para saber.
disk:
type: object
required:
- usedMb
- limitMb
properties:
usedMb:
type:
- integer
- 'null'
description: Espaço usado. `null` quando não dá para saber agora.
limitMb:
type: integer
description: Espaço do banco (2048).
externalAccess:
type: object
description: >-
O [acesso externo](/hosting/databases#acesso-externo): conectar de
fora da Cube com o certificado de cliente do banco.
required:
- isAvailable
- isEnabled
- host
- certificate
properties:
isAvailable:
type: boolean
description: '`false` = o acesso externo ainda não está liberado.'
isEnabled:
type: boolean
description: >-
Tem um certificado valendo: quem tiver ele e a senha conecta de
fora.
host:
type: string
description: '`db.cubehost.dev`, ou `mysql.cubehost.dev` no MySQL.'
certificate:
oneOf:
- type: object
required:
- createdAt
- expiresAt
properties:
createdAt:
type: string
format: date-time
expiresAt:
type: string
format: date-time
description: Depois disso o certificado para; gere outro no painel.
- type: 'null'
description: '`null` com o acesso desligado.'
startedAt:
type:
- string
- 'null'
format: date-time
description: Desde quando está no ar.
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
Error:
type: object
required:
- status
- code
- message
properties:
status:
type: string
const: error
code:
type: string
description: Código fixo em inglês. Veja [Códigos de erro](/errors).
message:
type: string
description: Texto em português para mostrar a uma pessoa.
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Chave de API da Cube (`cube_…`), criada no painel em **Chaves de API**.
Mande como `Authorization: Bearer cube_…`.
````