API de dados do Lakebase

info

Visualização

Este recurso está em Pré-visualização Pública nas seguintes regiões: us-east-1, us-west-2, eu-west-1.

O Lakebase autoscale é a nova versão do Lakebase com recursos como autoscale compute, escala-to-zero, branching e instant restore. Para comparação de recursos com o provisionamento do Lakebase, veja escolhendo entre versões.

A API de Dados do Lakebase é uma interface RESTful compatível com PostgREST que permite interagir diretamente com seu banco de dados Postgres do Lakebase usando métodos HTTP padrão. Oferece um endpoint API derivado do esquema do seu banco de dados, permitindo operações CRUD (Criar, Ler, Atualizar, Excluir) seguras em seus dados sem a necessidade de desenvolvimento de backend personalizado.

Visão geral

A API de Dados gera automaticamente um endpoint RESTful com base no esquema do seu banco de dados. Cada tabela em seu banco de dados torna-se acessível por meio de solicitações HTTP, permitindo que você:

• Consulte dados usando solicitações HTTP GET com filtragem, classificação e paginação flexíveis.
• Inserir registros usando solicitações HTTP POST
• Atualizar registros usando solicitações HTTP PATCH ou PUT
• Excluir registros usando solicitações HTTP DELETE
• Executar funções como RPCs usando solicitações HTTP POST

Essa abordagem elimina a necessidade de escrever e manter código de API personalizado, permitindo que você se concentre na lógica do seu aplicativo e no esquema do banco de dados.

Compatibilidade com PostgREST

A API de dados do Lakebase é compatível com a especificação PostgREST . Você pode:

• Utilize a biblioteca e as ferramentas de cliente PostgREST existentes.
• Siga as convenções do PostgREST para filtragem, ordenação e paginação.
• Adapte a documentação e os exemplos da comunidade PostgREST.

nota

A API de dados Lakebase é a implementação da Databricks projetada para ser compatível com a especificação PostgREST. Como a API de Dados é uma implementação independente, alguns recursos do PostgREST que não são aplicáveis ao ambiente Lakebase não estão incluídos. Para obter detalhes sobre a compatibilidade de recursos, consulte a referência de compatibilidade de recursos.

Para obter detalhes completos sobre recursos API , parâmetros de consulta e funcionalidades, consulte a referência API PostgREST.

Casos de uso

A API de dados do Lakebase é ideal para:

• Aplicações Web : Crie interfaces que interajam diretamente com seu banco de dados por meio de requisições HTTP.
• Microsserviços : Crie serviços leves que acessem recursos de banco de dados por meio APIs REST
• Arquiteturas sem servidor : Integre com funções serverless e plataformas de computação de borda.
• Aplicativos móveis : Forneça aos aplicativos móveis acesso direto ao banco de dados por meio de uma interface RESTful.
• Integrações com terceiros : Permitem que sistemas externos leiam e gravem dados com segurança.

Configure a API de Dados.

Esta seção orienta você na configuração da API de Dados, desde a criação das funções necessárias até a realização da sua primeira solicitação API .

Pré-requisitos

A API de Dados requer um projeto de banco de dados Lakebase Postgres com escalonamento automático. Se você não tiver um, consulte Introdução a projetos de banco de dados.

dica

Se precisar de tabelas de exemplo para testar a API de Dados, crie-as antes de ativar a API de Dados. Consulte o esquema de exemplo para obter um esquema completo de exemplo.

Ative a API de Dados

A API de dados faz todo o acesso ao banco de dados por meio de uma única função do Postgres chamada authenticator, que não requer permissões, exceto fazer log in. Ao ativar a API de Dados por meio do aplicativo Lakebase, essa função e a infraestrutura necessária são criadas automaticamente.

Para ativar a API de Dados:

1. Acesse a página da API de Dados no seu projeto.
2. Clique em Ativar API de Dados .

Isso executa automaticamente todas as etapas de configuração, incluindo a criação da função authenticator , a configuração do esquema pgrst e a exposição do esquema public por meio da API.

nota

Se você precisar expor esquemas adicionais (além de public), você pode modificar os esquemas expostos nas configurações da API de Dados Avançados.

Após ativar a API de Dados

Após ativar a API de Dados, o aplicativo Lakebase exibe a página APIde Dados com duas guias: API e Configurações .

A tab API fornece:

• URL da API : O URL do endpoint REST a ser usado no código do seu aplicativo e nas solicitações da API. A URL exibida não inclui o esquema, portanto, você deve adicionar o nome do esquema (por exemplo, /public) à URL ao fazer solicitações de API.
• Atualizar cache de esquema : Um botão para refresh o cache de esquema da API após fazer alterações no esquema do seu banco de dados. Consulte a seção sobre atualização do cache de esquema.
• Proteja seus dados : Opções para habilitar a segurança em nível de linha (RLS) do Postgres para suas tabelas. Consulte Ativar segurança em nível de linha.

A tab Configurações oferece opções para configurar o comportamento API , como esquemas expostos, número máximo de linhas, configurações de CORS e muito mais. Consulte as configurações avançadas da API de dados.

Exemplo de esquema (opcional)

Os exemplos nesta documentação utilizam o seguinte esquema. Você pode criar suas próprias tabelas ou usar este esquema de exemplo para testes. Execute essas instruções SQL usando o Editor SQL do Lakebase ou qualquer cliente SQL :

SQL

-- Create clients table
CREATE TABLE clients (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT UNIQUE NOT NULL,
  company TEXT,
  phone TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Create projects table with foreign key to clients
CREATE TABLE projects (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  description TEXT,
  client_id INTEGER NOT NULL REFERENCES clients(id) ON DELETE CASCADE,
  status TEXT DEFAULT 'active',
  start_date DATE,
  end_date DATE,
  budget DECIMAL(10,2),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Create tasks table with foreign key to projects
CREATE TABLE tasks (
  id SERIAL PRIMARY KEY,
  title TEXT NOT NULL,
  description TEXT,
  project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
  status TEXT DEFAULT 'pending',
  priority TEXT DEFAULT 'medium',
  assigned_to TEXT,
  due_date DATE,
  estimated_hours DECIMAL(5,2),
  actual_hours DECIMAL(5,2),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Insert sample data
INSERT INTO clients (name, email, company, phone) VALUES
  ('Acme Corp', 'contact@acme.com', 'Acme Corporation', '+1-555-0101'),
  ('TechStart Inc', 'hello@techstart.com', 'TechStart Inc', '+1-555-0102'),
  ('Global Solutions', 'info@globalsolutions.com', 'Global Solutions Ltd', '+1-555-0103');

INSERT INTO projects (name, description, client_id, status, start_date, end_date, budget) VALUES
  ('Website Redesign', 'Complete overhaul of company website with modern design', 1, 'active', '2024-01-15', '2024-06-30', 25000.00),
  ('Mobile App Development', 'iOS and Android app for customer management', 1, 'planning', '2024-07-01', '2024-12-31', 50000.00),
  ('Database Migration', 'Migrate legacy system to cloud database', 2, 'active', '2024-02-01', '2024-05-31', 15000.00),
  ('API Integration', 'Integrate third-party services with existing platform', 3, 'completed', '2023-11-01', '2024-01-31', 20000.00);

INSERT INTO tasks (title, description, project_id, status, priority, assigned_to, due_date, estimated_hours, actual_hours) VALUES
  ('Design Homepage', 'Create wireframes and mockups for homepage', 1, 'in_progress', 'high', 'Sarah Johnson', '2024-03-15', 16.00, 8.00),
  ('Setup Development Environment', 'Configure local development setup', 1, 'completed', 'medium', 'Mike Chen', '2024-02-01', 4.00, 3.50),
  ('Database Schema Design', 'Design new database structure', 3, 'completed', 'high', 'Alex Rodriguez', '2024-02-15', 20.00, 18.00),
  ('API Authentication', 'Implement OAuth2 authentication flow', 4, 'completed', 'high', 'Lisa Wang', '2024-01-15', 12.00, 10.50),
  ('User Testing', 'Conduct usability testing with target users', 1, 'pending', 'medium', 'Sarah Johnson', '2024-04-01', 8.00, NULL),
  ('Performance Optimization', 'Optimize database queries and caching', 3, 'in_progress', 'medium', 'Alex Rodriguez', '2024-04-30', 24.00, 12.00);

Configurar permissões de usuário

Você deve autenticar todas as solicitações da API de Dados usando tokens de portador OAuth do Databricks, que são enviados por meio do cabeçalho Authorization . A API de Dados restringe o acesso a identidades autenticadas do Databricks, com o Postgres gerenciando as permissões subjacentes.

A função authenticator assume a identidade do usuário solicitante ao processar solicitações de API. Para que isso funcione, cada identidade do Databricks que acessa a API de Dados deve ter uma função correspondente no Postgres em seu banco de dados. Se você precisar adicionar usuários à sua account Databricks primeiro, consulte Adicionar usuários à sua account.

Adicionar funções do Postgres

Use a extensão databricks_auth para criar funções do Postgres que correspondam às identidades do Databricks:

Criar a extensão:

SQL

CREATE EXTENSION IF NOT EXISTS databricks_auth;

Adicionar uma função do Postgres:

SQL

SELECT databricks_create_role('user@databricks.com', 'USER');

Para obter instruções detalhadas, consulte Criar uma função OAuth para uma identidade Databricks usando SQL.

importante

Não utilize a account de proprietário do banco de dados (a identidade Databricks que criou o projeto Lakebase) para acessar a API de Dados. A função authenticator requer a capacidade de assumir sua função, e essa permissão não pode ser concedida para contas com privilégios elevados.

Se você tentar conceder a função de proprietário do banco de dados a authenticator, receberá este erro:

ERROR:  permission denied to grant role "db_owner_user@databricks.com"
DETAIL:  Only roles with the ADMIN option on role "db_owner_user@databricks.com" may grant this role.

Conceder permissões aos usuários

Agora que você criou as funções correspondentes do Postgres para suas identidades do Databricks, precisa conceder permissões a essas funções do Postgres. Essas permissões controlam com quais objetos do banco de dados (esquemas, tabelas, sequências, funções) cada usuário pode interagir por meio de solicitações de API.

Conceda permissões usando instruções SQL padrão GRANT . Este exemplo usa o esquema public ; se você estiver expondo um esquema diferente, substitua public pelo nome do seu esquema:

SQL

-- Allow authenticator to assume the identity of the user
GRANT "user@databricks.com" TO authenticator;

-- Allow user@databricks.com to access everything in public schema
GRANT USAGE ON SCHEMA public TO "user@databricks.com";
GRANT SELECT, UPDATE, INSERT, DELETE ON ALL TABLES IN SCHEMA public TO "user@databricks.com";
GRANT USAGE ON ALL SEQUENCES IN SCHEMA public TO "user@databricks.com";
GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA public TO "user@databricks.com";

Este exemplo concede acesso total ao esquema public para a identidade user@databricks.com . Substitua isso pela identidade real do Databricks e ajuste as permissões de acordo com suas necessidades.

importante

Implementar segurança em nível de linha : As permissões acima concedem acesso em nível de tabela, mas a maioria dos casos de uso da API requer restrições em nível de linha. Por exemplo, em aplicações multi-tenant , os usuários devem visualizar apenas seus próprios dados ou os dados de sua organização. Utilize políticas de segurança em nível de linha (RLS) do PostgreSQL para impor um controle de acesso refinado no nível do banco de dados. Consulte Implementar segurança em nível de linha.

Autenticação

Para acessar a API de Dados, você deve fornecer um token OAuth Databricks no cabeçalho Authorization da sua solicitação HTTP. A identidade autenticada Databricks deve ter uma função correspondente no Postgres (criada nas etapas anteriores) que defina suas permissões de banco de dados.

Obtenha um token OAuth

Conecte-se ao seu workspace como a identidade Databricks para a qual você criou uma função Postgres nas etapas anteriores e obtenha um token OAuth . Consulte a seção Autenticação para obter instruções.

Fazer um pedido

Com seus tokens OAuth e URL API (disponíveis na tab API do aplicativo Lakebase), você pode fazer solicitações API usando curl ou qualquer cliente HTTP. Lembre-se de adicionar o nome do esquema (por exemplo, /public) ao URL da API. Os exemplos a seguir pressupõem que você exportou a variável de ambiente DBX_OAUTH_TOKEN e REST_ENDPOINT .

Aqui está um exemplo de chamada com a saída esperada (usando o esquema de exemplo clients/projects/tarefa):

Bash

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/clients?select=id,name,projects(id,name)&id=gte.2"

Resposta de exemplo:

JSON

[
  { "id": 2, "name": "TechStart Inc", "projects": [{ "id": 3, "name": "Database Migration" }] },
  { "id": 3, "name": "Global Solutions", "projects": [{ "id": 4, "name": "API Integration" }] }
]

Para mais exemplos e informação detalhada sobre operações API , consulte a secção de referênciaAPI . Para obter detalhes completos sobre parâmetros de consulta e recursos da API, consulte a referência da API PostgREST. Para informações de compatibilidade específicas do Lakebase, consulte Compatibilidade com PostgREST.

Antes de usar a API extensivamente, configure a segurança em nível de linha para proteger seus dados.

Gerenciar a APIde Dados

Após habilitar a API de Dados, você poderá gerenciar alterações de esquema e configurações de segurança por meio do aplicativo Lakebase.

atualizar cache de esquema

Ao fazer alterações no esquema do seu banco de dados (adicionando tabelas, colunas ou outros objetos de esquema), você precisa refresh o cache do esquema. Isso torna suas alterações imediatamente disponíveis por meio da API de Dados.

Para refresh o cache de esquema:

1. Acesse a API de Dados na seção Backend do aplicativo do seu projeto.
2. Clique em Atualizar cache de esquema .

A API de Dados agora reflete suas alterações de esquema mais recentes.

Ativar segurança em nível de linha

O aplicativo Lakebase oferece uma maneira rápida de habilitar a segurança em nível de linha (RLS) para tabelas em seu banco de dados. Quando existem tabelas no seu esquema, a tab API exibe uma seção "Proteja seus dados" que mostra:

• Tabelas com RLS ativado
• Tabelas com RLS desativado (com avisos)
• Um botão "Ativar RLS" para habilitar o RLS para todas as tabelas.

importante

Habilitar o RLS por meio do aplicativo Lakebase ativa a segurança em nível de linha para suas tabelas. Quando o RLS está ativado, todas as linhas ficam inacessíveis aos usuários por default (exceto para proprietários de tabelas, funções com o atributo BYPASSRLS e superusuários — embora os superusuários não sejam suportados no Lakebase). Você deve criar políticas RLS para conceder acesso a linhas específicas com base em seus requisitos de segurança. Consulte Segurança em nível de linha para obter informações sobre como criar políticas.

Para ativar a segurança RLS em suas tabelas:

1. Acesse a API de Dados na seção Backend do aplicativo do seu projeto.
2. Na seção "Proteja seus dados" , revise as tabelas que não têm o RLS ativado.
3. Clique em Ativar RLS para habilitar a segurança em nível de linha para todas as tabelas.

Você também pode habilitar a segurança RLS para tabelas individuais usando SQL. Consulte Segurança em nível de linha para obter detalhes.

Configurações avançadas da API de dados

A seção Configurações avançadas na tab API do aplicativo Lakebase controla a segurança, o desempenho e o comportamento do seu endpoint API de dados.

Esquemas expostos

padrão: public

Define quais esquemas PostgreSQL são expostos como endpoints API REST . Por default, apenas o esquema public está acessível. Se você usar outros esquemas (por exemplo, api, v1), selecione-os na lista suspensa para adicioná-los.

nota

Aplicam-se permissões: Adicionar um esquema aqui expõe o endpoint, mas a função de banco de dados usada pela API ainda deve ter privilégios USAGE no esquema e privilégios SELECT nas tabelas.

Número máximo de linhas

padrão: Vazio

Impõe um limite rígido ao número de linhas a serem retornadas em uma única resposta da API. Isso evita a degradação acidental do desempenho causada por consultas extensas. Os clientes devem usar limites de paginação para recuperar dados dentro desse limite. Isso também evita custos inesperados de saída decorrentes de grandes transferências de dados.

Origens permitidas pelo CORS

Padrão: Vazio (Permite todas as origens)

Controla quais domínios da web podem obter dados da sua API usando um navegador.

• Vazio: Permite * (qualquer domínio). Útil para desenvolvimento.
• Produção: Liste seus domínios específicos (por exemplo, https://myapp.com) para impedir que sites não autorizados consultem sua API.

Especificação OpenAPI

Padrão: Desativado

Controla se um esquema OpenAPI 3 gerado automaticamente está disponível em /openapi.json. Este esquema descreve suas tabelas, colunas e endpoint REST . Quando ativado, você poderá usá-lo para:

• Gerar documentação de API (Swagger UI, Redoc)
• Criar biblioteca cliente tipada (TypeScript, Python, Go)
• Importe sua API para o Postman.
• Integre com gateways de API e outras ferramentas baseadas em OpenAPI.

Cabeçalhos de tempo do servidor

Padrão: Desativado

Quando ativada, a API de Dados inclui cabeçalhos Server-Timing em cada resposta. Esses cabeçalhos mostram quanto tempo diferentes partes da solicitação levaram para serem processadas (por exemplo, tempo de execução do banco de dados e tempo de processamento interno). Você pode usar essas informações para depurar consultas lentas, medir o desempenho e solucionar problemas de latência em seu aplicativo.

nota

Após alterar as configurações avançadas, clique em Salvar para aplicá-las.

Segurança em nível de linha

As políticas de segurança em nível de linha (RLS) fornecem controle de acesso refinado, restringindo quais linhas os usuários podem acessar em uma tabela.

Como o RLS funciona com a API de Dados : Quando um usuário faz uma solicitação de API, a função authenticator assume a identidade desse usuário. Quaisquer políticas RLS definidas para a função desse usuário são aplicadas automaticamente pelo PostgreSQL, filtrando os dados aos quais ele pode acessar. Isso ocorre no nível do banco de dados, portanto, mesmo que o código do aplicativo tente consultar todas as linhas, o banco de dados retorna apenas as linhas que o usuário tem permissão para visualizar. Isso proporciona segurança em camadas sem exigir lógica de filtragem no código do seu aplicativo.

Por que a segurança em nível de linha (RLS) é fundamental para APIs : Ao contrário das conexões diretas com o banco de dados, onde você controla o contexto da conexão, APIs HTTP expõem seu banco de dados a vários usuários por meio de um único endpoint. As permissões ao nível da tabela significam que, se um utilizador puder aceder à tabela clients , poderá aceder a todos os registos do cliente, a menos que implemente filtragem. As políticas RLS garantem que cada usuário veja automaticamente apenas os dados que lhe foram autorizados.

A síndrome das pernas inquietas é essencial para:

• Aplicações multi-tenant : Isolam dados entre diferentes clientes ou organizações.
• Dados pertencentes ao usuário : Garanta que os usuários acessem apenas seus próprios registros.
• Acesso baseado em equipe : limite a visibilidade a membros da equipe ou grupos específicos.
• Requisitos de conformidade : Impor restrições de acesso a dados no nível do banco de dados.

Ativar RLS

Você pode habilitar o RLS através do aplicativo Lakebase ou usando instruções SQL. Para obter instruções sobre como usar o aplicativo Lakebase, consulte Ativar segurança em nível de linha.

atenção

Se você tiver tabelas sem RLS habilitado, a tab API no aplicativo Lakebase exibirá um aviso de que usuários autenticados podem view todas as linhas nessas tabelas. A API de Dados interage diretamente com o seu esquema Postgres e, como a API é acessível pela internet, é crucial reforçar a segurança no nível do banco de dados usando a segurança em nível de linha do PostgreSQL.

Para habilitar RLS usando SQL, execute o seguinte comando:

SQL

ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

Criar políticas RLS

Após habilitar o RLS em uma tabela, você deve criar políticas que definam as regras de acesso. Sem políticas, os usuários não podem acessar nenhuma linha (todas as linhas ficam ocultas por default).

Como funcionam as políticas : Quando a segurança em nível de linha (RLS) está habilitada em uma tabela, os usuários só podem ver as linhas que correspondem a pelo menos uma política. Todas as outras linhas foram filtradas. Proprietários de tabelas, funções com o atributo BYPASSRLS e superusuários podem ignorar o sistema de segurança de linhas (embora os superusuários não sejam suportados no Lakebase).

nota

No Lakebase, current_user retorna o endereço email do usuário autenticado (por exemplo, user@databricks.com). Utilize isso em suas políticas de RLS para identificar qual usuário está fazendo a solicitação.

Sintaxe básica da política:

SQL

CREATE POLICY policy_name ON table_name
  [TO role_name]
  USING (condition);

• policy_name : Um nome descritivo para a política.
• table_name : A tabela à qual a política será aplicada.
• PARA nome_da_função : Opcional. Especifica a função desta política. Omita esta cláusula para aplicar a política a todas as funções.
• USANDO (condição) : A condição que determina quais linhas são visíveis.

tutorialRLS

O tutorial a seguir utiliza o esquema de exemplo desta documentação (tabelas de clientes, projetos e tarefas) para mostrar como implementar a segurança em nível de linha.

Cenário : Você tem vários usuários que devem visualizar apenas os clientes e projetos relacionados que lhes foram atribuídos. Restrinja o acesso para que:

• alice@databricks.com Só é possível view clientes com IDs 1 e 2.
• bob@databricks.com Só é possível view clientes com IDs 2 e 3.

Passo 1: Habilitar RLS na tabela de clientes

SQL

ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

o passo 2: Crie uma política para Alice

SQL

CREATE POLICY alice_clients ON clients
  TO "alice@databricks.com"
  USING (id IN (1, 2));

o passo 3: Crie uma política para Bob

SQL

CREATE POLICY bob_clients ON clients
  TO "bob@databricks.com"
  USING (id IN (2, 3));

o passo 4: Teste as políticas

Quando Alice faz uma solicitação à API:

Bash

# Alice's token in the Authorization header
curl -H "Authorization: Bearer $ALICE_TOKEN" \
  "$REST_ENDPOINT/public/clients?select=id,name"

Resposta (Alice atende apenas os clientes 1 e 2):

JSON

[
  { "id": 1, "name": "Acme Corp" },
  { "id": 2, "name": "TechStart Inc" }
]

Quando Bob faz uma solicitação à API:

Bash

# Bob's token in the Authorization header
curl -H "Authorization: Bearer $BOB_TOKEN" \
  "$REST_ENDPOINT/public/clients?select=id,name"

Resposta (Bob só atende os clientes 2 e 3):

JSON

[
  { "id": 2, "name": "TechStart Inc" },
  { "id": 3, "name": "Global Solutions" }
]

Padrões comuns de síndrome das pernas inquietas

Esses padrões abrangem os requisitos de segurança típicos da API de Dados:

Propriedade do usuário - Restringe as linhas ao usuário autenticado:

SQL

CREATE POLICY user_owned_data ON tasks
  USING (assigned_to = current_user);

Isolamento de locatário - Restringe as linhas à organização do usuário:

SQL

CREATE POLICY tenant_data ON clients
  USING (tenant_id = (
    SELECT tenant_id
    FROM user_tenants
    WHERE user_email = current_user
  ));

Associação de equipe - Restringe as linhas às equipes do usuário:

SQL

CREATE POLICY team_projects ON projects
  USING (client_id IN (
    SELECT client_id
    FROM team_clients
    WHERE team_id IN (
      SELECT team_id
      FROM user_teams
      WHERE user_email = current_user
    )
  ));

Acesso baseado em funções - Restringe o número de linhas com base na associação à função:

SQL

CREATE POLICY manager_access ON tasks
  USING (
    status = 'pending' OR
    pg_has_role(current_user, 'managers', 'member')
  );

Acesso somente leitura para funções específicas - Políticas diferentes para operações diferentes:

SQL

-- Allow all users to read their assigned tasks
CREATE POLICY read_assigned_tasks ON tasks
  FOR SELECT
  USING (assigned_to = current_user);

-- Only managers can update tasks
CREATE POLICY update_tasks ON tasks
  FOR UPDATE
  TO "managers"
  USING (true);

Recursos adicionais

Para obter informações completas sobre a implementação de RLS, incluindo tipos de política, melhores práticas de segurança e padrões avançados, consulte a documentação de Políticas de Segurança de LinhasPostgreSQL.

Para mais informações sobre permissões, veja gerenciar permissões.

Referência da API

Esta seção pressupõe que você já concluiu a configuração dos passos, configurou as permissões e implementou a segurança em nível de linha. As seções a seguir fornecem informações de referência para o uso da API de Dados, incluindo operações comuns, recursos avançados, considerações de segurança e detalhes de compatibilidade.

Operações básicas

Registros de consulta

Recuperar registros de uma tabela usando o método HTTP GET:

Bash

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/clients"

Resposta de exemplo:

JSON

[
  { "id": 1, "name": "Acme Corp", "email": "contact@acme.com", "company": "Acme Corporation", "phone": "+1-555-0101" },
  {
    "id": 2,
    "name": "TechStart Inc",
    "email": "hello@techstart.com",
    "company": "TechStart Inc",
    "phone": "+1-555-0102"
  }
]

Filtrar resultados

Utilize parâmetros de consulta para filtrar os resultados. Este exemplo recupera clientes com id maior ou igual a 2:

Bash

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/clients?id=gte.2"

Resposta de exemplo:

JSON

[
  { "id": 2, "name": "TechStart Inc", "email": "hello@techstart.com" },
  { "id": 3, "name": "Global Solutions", "email": "info@globalsolutions.com" }
]

Selecione colunas específicas e join tabelas.

Utilize o parâmetro select para recuperar colunas específicas e join tabelas relacionadas:

Bash

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/clients?select=id,name,projects(id,name)&id=gte.2"

Resposta de exemplo:

JSON

[
  { "id": 2, "name": "TechStart Inc", "projects": [{ "id": 3, "name": "Database Migration" }] },
  { "id": 3, "name": "Global Solutions", "projects": [{ "id": 4, "name": "API Integration" }] }
]

Inserir registros

Criar novos registros usando HTTP POST:

Bash

curl -X POST \
  -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Client",
    "email": "newclient@example.com",
    "company": "New Company Inc",
    "phone": "+1-555-0104"
  }' \
  "$REST_ENDPOINT/public/clients"

Atualizar registros

Atualizar registros existentes usando HTTP PATCH:

Bash

curl -X PATCH \
  -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+1-555-0199"}' \
  "$REST_ENDPOINT/public/clients?id=eq.1"

Excluir registros

Excluir registros usando HTTP DELETE:

Bash

curl -X DELETE \
  -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/clients?id=eq.5"

Recurso avançado

Paginação

Controle o número de registros retornados usando os parâmetros limit e offset :

Bash

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/tasks?limit=10&offset=0"

Classificação

Ordenar resultados usando o parâmetro order :

Bash

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/tasks?order=due_date.desc"

Filtragem complexa

Combinar várias condições de filtro:

Bash

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/tasks?status=eq.in_progress&priority=eq.high"

Operadores de filtro comuns:

• eq - igual a
• gte - maior ou igual a
• lte - menor ou igual a
• neq - não igual
• like - reconhecimento de padrões
• in - corresponde a qualquer valor na lista

Para mais informações sobre parâmetros de consulta suportados e recursos API , consulte a referência API PostgREST. Para informações de compatibilidade específicas do Lakebase, consulte Compatibilidade com PostgREST.

Referência de compatibilidade de recursos

Esta seção lista os recursos do PostgREST que têm comportamento diferente ou não são suportados na API de Dados do Lakebase.

Autenticação e autorização

Recurso	Status	Detalhes
Configuração JWT	Não aplicável	A API de dados do Lakebase usa tokens OAuth do Databricks em vez de autenticação JWT. As opções de configuração específicas do JWT (segredos personalizados, chave RS256, validação de público-alvo) não estão disponíveis.

incorporação de recursos

Recurso	Status	Detalhes
calcular relações	Não suportado	Não são suportadas relações personalizadas definidas por meio de funções de banco de dados que retornam SETOF ou registros únicos. Somente relacionamentos key estrangeira podem ser incorporados.
Incorporação join interna ( dica !inner )	Não suportado	A dica !inner que converte o left join em inner join para filtrar linhas pai com base em critérios filho não é suportada. Exemplo: ?select=*,clients!inner(*)&clients.id=eq.1

Formatos de resposta

Recurso	Status	Detalhes
manipuladores de tipo de mídia personalizados	Não suportado	Não há suporte para formatos de saída personalizados por meio de agregações do PostgreSQL (formatos binários, XML, buffers de protocolo).
Nulos removidos	Não suportado	O parâmetro de tipo de mídia nulls=stripped que remove campos nulos de respostas JSON não é suportado. Exemplo: Accept: application/vnd.pgrst.object+json;nulls=stripped
PostGIS GeoJSON	Parcialmente apoiado	As colunas de geometria do PostGIS podem ser consultadas, mas a formatação automática do GeoJSON via cabeçalho Accept: application/geo+json não está disponível.

Paginação e contagem

Recurso	Status	Detalhes
Contagem planejada	Não suportado	A opção Prefer: count=planned que usa o planejador de consultas do PostgreSQL para estimar a contagem de resultados não é suportada. Use Prefer: count=exact em vez disso.
Contagem estimada	Não suportado	A opção Prefer: count=estimated que usa estatísticas do PostgreSQL para contagens aproximadas não é suportada. Use Prefer: count=exact em vez disso.

Solicitar preferências

Recurso	Status	Detalhes
Preferência de fuso horário	Parcialmente apoiado	O tratamento de fuso horário existe, mas o cabeçalho Prefer: timezone=America/Los_Angeles para substituir o fuso horário do servidor não é suportado. Configure o fuso horário do servidor ou utilize funções de fuso horário no nível do banco de dados.
Controle de transação	Não suportado	O controle de transações por meio dos cabeçalhos Prefer: tx=commit e Prefer: tx=rollback não é suportado.
Modos de gerenciamento de preferências	Não suportado	As opções Prefer: handling=strict e Prefer: handling=lenient para controlar como as preferências inválidas são tratadas não são suportadas.

Observabilidade

A API de dados do Lakebase implementa seu próprio recurso de observabilidade. Os seguintes recursos de observabilidade do PostgREST não são suportados:

Recurso	Status	Detalhes
Exposição do plano de consulta	Não suportado	O cabeçalho Accept: application/vnd.pgrst.plan+json que expõe a saída do EXPLAIN do PostgreSQL para análise de desempenho não é suportado.
Cabeçalho de temporização do servidor	Não suportado	O cabeçalho Server-Timing, que fornece a discriminação do tempo de resposta das solicitações, não é suportado. O Lakebase implementa seu próprio recurso de observabilidade.
Propagação do cabeçalho de rastreamento	Não suportado	A propagação do cabeçalho X-Request-Id e do cabeçalho de rastreamento personalizado para rastreamento distribuído não é suportada. O Lakebase implementa seu próprio recurso de observabilidade.

Configuração avançada

Recurso	Status	Detalhes
Configurações do aplicativo (GUCs)	Não suportado	Não há suporte para passar valores de configuração personalizados para funções de banco de dados por meio de GUCs do PostgreSQL.
Função de pré-requisição	Não suportado	A configuração db-pre-request que permite especificar uma função de banco de dados para execução antes de cada solicitação não é suportada.

Para mais informações sobre o recurso PostgREST, consulte a documentação do PostgREST.

Considerações de segurança

A API de Dados reforça o modelo de segurança do seu banco de dados em vários níveis:

• Autenticação : Todas as solicitações exigem autenticação com tokens OAuth válidos.
• Acesso baseado em funções : as permissões em nível de banco de dados controlam quais tabelas e operações os usuários podem acessar.
• Segurança em nível de linha : as políticas RLS impõem um controle de acesso refinado, restringindo quais linhas específicas os usuários podem visualizar ou modificar.
• Contexto do usuário : A API pressupõe a identidade do usuário autenticado, garantindo que as permissões e políticas do banco de dados sejam aplicadas corretamente.

Práticas de segurança recomendadas

Para implantações em produção:

1. Implemente segurança em nível de linha : Use políticas RLS para restringir o acesso a dados em nível de linha. Isso é especialmente importante para aplicações com múltiplostenant e dados de propriedade do usuário. Consulte Segurança em nível de linha.
2. Conceder permissões mínimas : Conceda apenas as permissões que os usuários precisam (SELECT, INSERT, UPDATE, DELETE) em tabelas específicas, em vez de conceder acesso amplo.
3. Utilize funções separadas por aplicação : Crie funções dedicadas para diferentes aplicações ou serviços, em vez de compartilhar uma única função.
4. Audite o acesso regularmente : revise periodicamente as permissões concedidas e as políticas de RLS para garantir que estejam de acordo com seus requisitos de segurança.

Para obter informações sobre como gerenciar funções e permissões, consulte:

• Gerenciar funções do Postgres
• Gerenciar permissões