Strings de Conexão

Conecte suas aplicações a bancos de dados com variáveis de ambiente injetadas automaticamente. O sh0 cuida da rede interna para que sua aplicação alcance seu banco de dados pelo hostname.

Encontrando Strings de Conexão

Todo banco de dados criado no sh0 tem seus detalhes de conexão disponíveis no painel. Navegue até a página de detalhes do banco de dados e clique na aba Conexão para ver todas as informações de conexão.

A aba de conexão exibe:

• URL de conexão completa -- Pronta para copiar e colar na configuração da sua aplicação.
• Campos individuais -- Host, porta, usuário, senha e nome do banco de dados como valores separados.
• Comando de conexão -- Um comando CLI para conectar diretamente (ex.: psql, mysql).

Por exemplo, uma string de conexão PostgreSQL se parece com:

postgresql://myuser:secretpass@mydb:5432/myapp

Variáveis de Ambiente Injetadas Automaticamente

Quando você cria um banco de dados em uma stack, o sh0 injeta automaticamente variáveis de ambiente de conexão em todos os serviços de aplicação dentro da mesma stack. Sua aplicação pode ler essas variáveis em tempo de execução sem nenhuma configuração manual.

Convenção de Nomenclatura de Variáveis

Variáveis injetadas automaticamente seguem um padrão de nomenclatura consistente baseado no nome e motor do banco de dados:

DATABASE_URL=postgresql://sh0:generated_pass@mydb:5432/sh0
MYDB_HOST=mydb
MYDB_PORT=5432
MYDB_USER=sh0
MYDB_PASSWORD=generated_pass
MYDB_DATABASE=sh0

DATABASE_URL=mysql://sh0:generated_pass@maindb:3306/sh0
MAINDB_HOST=maindb
MAINDB_PORT=3306
MAINDB_USER=sh0
MAINDB_PASSWORD=generated_pass
MAINDB_DATABASE=sh0

REDIS_URL=redis://:generated_pass@cache:6379
CACHE_HOST=cache
CACHE_PORT=6379
CACHE_PASSWORD=generated_pass

MONGO_URL=mongodb://sh0:generated_pass@docs:27017/sh0
DOCS_HOST=docs
DOCS_PORT=27017
DOCS_USER=sh0
DOCS_PASSWORD=generated_pass
DOCS_DATABASE=sh0

Conectando da Mesma Stack

Serviços dentro da mesma stack compartilham uma rede Docker. Isso significa que sua aplicação pode se conectar ao banco de dados usando o nome do contêiner do banco de dados como hostname. Sem endereços IP, sem mapeamento de porta -- apenas o nome do contêiner.

// The DATABASE_URL is auto-injected by sh0
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
});

# settings.py
import dj_database_url

DATABASES = {
    'default': dj_database_url.config(
        default=os.environ['DATABASE_URL']
    )
}

Acesso Externo

Por padrão, bancos de dados são acessíveis apenas de dentro da rede da stack. Para conectar da sua máquina local (por exemplo, usando uma ferramenta GUI como pgAdmin, TablePlus ou DBeaver), você precisa habilitar o acesso externo.

1. Abra as configurações do banco de dados.
2. Ative Acesso Público para habilitá-lo.
3. O sh0 mapeia a porta do contêiner para uma porta alta aleatória no host (ex.: 54321).
4. Conecte usando ip-do-seu-servidor:54321 com as credenciais do banco de dados.

Pooling de Conexão

A maioria dos bancos de dados tem um limite no número de conexões simultâneas. O pooling de conexão ajuda você a permanecer dentro desses limites enquanto atende muitas requisições.

Melhores práticas para pooling de conexão no sh0:

• Use o pool integrado do seu framework -- A maioria dos ORMs e drivers de banco de dados suporta pooling de conexão. Configure o tamanho do pool com base nos limites do seu banco de dados.
• Ajuste o tamanho do pool às conexões disponíveis -- O PostgreSQL tem por padrão 100 conexões máximas. Se você tem 3 réplicas de aplicação, defina cada pool para ~30 conexões.
• Defina timeouts de conexão -- Configure timeouts de conexão ociosa para evitar que conexões obsoletas consumam slots.
• Monitore a contagem de conexões -- Use o painel de métricas do banco de dados para rastrear conexões ativas ao longo do tempo.

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 20,              // Maximum connections in the pool
  idleTimeoutMillis: 30000,  // Close idle connections after 30s
  connectionTimeoutMillis: 5000, // Fail if connection takes > 5s
});

Exemplos para Frameworks Comuns

Aqui estão exemplos de conexão para frameworks populares. Todos usam a variável de ambiente DATABASE_URL que o sh0 injeta automaticamente.

production:
  url: <%= ENV['DATABASE_URL'] %>

DB_CONNECTION=pgsql
DB_HOST=${{ MYDB_HOST }}
DB_PORT=${{ MYDB_PORT }}
DB_DATABASE=${{ MYDB_DATABASE }}
DB_USERNAME=${{ MYDB_USER }}
DB_PASSWORD=${{ MYDB_PASSWORD }}

let pool = PgPoolOptions::new()
    .max_connections(20)
    .connect(&std::env::var("DATABASE_URL")?)
    .await?;

pool, err := pgxpool.New(ctx, os.Getenv("DATABASE_URL"))