Início rápido — Com banco de dados

Publique uma aplicação Node.js conectada a um banco PostgreSQL gerenciado.

Nota: Este quickstart foca em PostgreSQL. Para MariaDB, Analytics (ClickHouse) ou Valkey (Chave-Valor, Cache e Filas), use os guias específicos de Banco de Dados, Analytics e Serviços gerenciados.

Passo 1 — Crie o banco PostgreSQL

1. No console, crie um banco PostgreSQL gerenciado. Para testes, o plano db-free está disponível.
2. Escolha a versão desejada entre as opções disponíveis no console (15, 16, 17 ou 18).
3. Copie a URI completa ou os dados de conexão exibidos. A URI usa o host postgresql-<id-do-projeto>.managed.zenifra.com e exige TLS com sslmode=verify-full.
4. Guarde a URI para configurar a variável DATABASE_URL no projeto HTTP.

Importante: A Zenifra não injeta DATABASE_URL automaticamente na sua aplicação. Essa configuração deve ser feita manualmente no projeto HTTP antes da publicação ou em um novo deploy.

Passo 2 — Crie sua aplicação

mkdir zenifra-api
cd zenifra-api
npm init -y
npm install express pg

Crie index.js:

const express = require('express');
const { Pool } = require('pg');
const app = express();
app.use(express.json());

// A URI do console usa sslmode=verify-full&sslrootcert=system.
// O node-postgres não lê sslrootcert=system; com ssl: true ele valida
// o certificado e o hostname usando as autoridades confiáveis do Node.js.
const databaseUrl = new URL(process.env.DATABASE_URL);
databaseUrl.searchParams.delete('sslmode');
databaseUrl.searchParams.delete('sslrootcert');

const pool = new Pool({
  connectionString: databaseUrl.toString(),
  ssl: true,
});

app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

app.get('/', async (req, res, next) => {
  let client;

  try {
    client = await pool.connect();
    const { rows } = await client.query('SELECT NOW() as now');
    res.json({ database_time: rows[0].now });
  } catch (error) {
    next(error);
  } finally {
    if (client) client.release();
  }
});

app.post('/todos', async (req, res, next) => {
  const { task } = req.body;
  let client;

  try {
    client = await pool.connect();
    await client.query(
      'CREATE TABLE IF NOT EXISTS todos (id SERIAL PRIMARY KEY, task TEXT, done BOOLEAN DEFAULT false)'
    );
    const { rows } = await client.query('INSERT INTO todos (task) VALUES ($1) RETURNING *', [task]);
    res.status(201).json(rows[0]);
  } catch (error) {
    next(error);
  } finally {
    if (client) client.release();
  }
});

app.use((error, req, res, next) => {
  console.error(error);
  res.status(500).json({ error: 'Internal server error' });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, '0.0.0.0', () => {
  console.log(`API running on port ${PORT}`);
});

Passo 3 — Publique via GitHub

1. Crie um repositório no GitHub, adicione um script "start": "node index.js" ao package.json e faça push do código, incluindo o package-lock.json.
2. No console, escolha Origem do Projeto como Repositório Git e, em Provedor Git, selecione GitHub.
3. Selecione o repositório e a branch principal.
4. Em Runtime, selecione Node.js.
5. No campo Porta, informe 3000.
6. Configure a variável de ambiente DATABASE_URL com a URI do PostgreSQL criada no passo 1.
7. Em Comando Start, use npm start; deixe Comando Build vazio.
8. Se desejar atualização automática por push, selecione Automático por branch em Modo de deploy.
9. Clique em Criar Projeto.

Se o projeto HTTP já existir, salve a variável DATABASE_URL nele e publique uma nova versão para que a aplicação leia a ENV atualizada.

Passo 4 — Teste

Use a URL do projeto em *.clients.zenifra.com e valide a aplicação.

Verifique se a aplicação está no ar:

curl https://seu-projeto.clients.zenifra.com/health

Verifique a conexão com o banco:

curl https://seu-projeto.clients.zenifra.com/

Crie um item para validar escrita no PostgreSQL:

curl -X POST https://seu-projeto.clients.zenifra.com/todos \
  -H 'Content-Type: application/json' \
  -d '{"task":"Build something cool"}'

Resposta:

{ "id": 1, "task": "Build something cool", "done": false }

Variáveis de ambiente

Para esse fluxo, configure manualmente pelo menos esta variável e este campo:

A Zenifra também injeta ZENIFRA_INSTANCE_VERSION com a versão da instância publicada; não é preciso cadastrá-la.

Acesso ao banco

Use a URI completa ou os dados de conexão fornecidos no console para conectar sua aplicação ou ferramentas externas ao PostgreSQL gerenciado, sempre com TLS e validação do certificado. A Zenifra não oferece backup automático com restauração pelo console: mantenha seus próprios dumps (pg_dump) dos dados importantes.