Pular para o conteúdo principal

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
Este guia usa uma capability Preview. Inicie o servidor com --vsql_allow_preview_extensions=ON, ou o INSTALL EXTENSION é recusado.
Colocar um endpoint JSON somente leitura na frente de algumas tabelas geralmente significa escrever um serviço pequeno, implantá-lo, dar a ele uma conta de banco de dados e mantê-lo vivo. A extensão vsql_rest do VillageSQL serve essas tabelas de dentro do processo do servidor, então não há um segundo processo nem uma implantação nova. Os padrões foram feitos para uma máquina de desenvolvedor, não para uma rede. Leia “Antes de expor a porta” abaixo antes de abri-la para qualquer coisa.

Ligando

Crie o banco de dados e as suas tabelas primeiro. O listener lê o layout do banco de dados quando inicia e o guarda em cache por vsql_rest.schema_ttl segundos, 60 por padrão, então uma tabela criada depois responde table not found até esse cache expirar.
Depois, informe o banco de dados, informe as tabelas que você está disposto a servir e inicie o listener:

Lendo

Uma tabela é um caminho, e a query string faz a filtragem. Cada filtro é coluna=operador.valor:
Peça as colunas que você quer, e nada mais:
Combine condições com or=(...):
Pagine com limit e offset:
Os operadores são eq, neq, lt, lte, gt, gte, like, cs_like, in e is. in recebe uma lista, como em ?id=in.(1,3), e is recebe null, como em ?price=is.null ou ?price=is.not.null. Uma requisição sem limit retorna no máximo vsql_rest.max_rows linhas, que começa em 1000.

A allowlist

Uma tabela que não está em allowed_tables não existe para a API:
A resposta é 404, e ela é igual quer a tabela não exista, quer apenas não tenha sido liberada.
Deixar allowed_tables vazio não significa nenhuma tabela. Significa todas elas. Defina-o com as tabelas que você pretende publicar antes de habilitar o listener.

Restringindo métodos por tabela

table_methods diz quais métodos HTTP cada tabela aceita, como tabela:MÉTODO,MÉTODO com um | entre as tabelas:
Por padrão, toda tabela aceita todos os métodos, então defina isso antes de o listener iniciar. Um método que a tabela não concede é recusado:
Conceder gravações é a mesma configuração:
Uma inserção bem-sucedida responde 201 com um corpo vazio. Uma chave duplicada volta como 409:

Observando o funcionamento

Cinco contadores de status reportam sobre o listener, incluindo a porta que ele de fato vinculou:
http_port mostra 0 quando nada está escutando, que é a forma mais rápida de saber se o listener iniciou. Definir vsql_rest.port como 0 pede ao sistema operacional que escolha uma porta, e esse contador é onde você lê qual porta ele escolheu.

Antes de expor a porta

Os padrões deixam o acesso aberto, e cada um deles é razoável isoladamente. require_auth começa em OFF, então nenhuma requisição carrega ou precisa de um token. Um allowed_tables vazio publica o schema inteiro. Um table_methods vazio permite todos os métodos, incluindo DELETE, e um DELETE contra um listener nesse estado tem sucesso:
Ele responde 204, e a linha se foi. Somando tudo, um listener ligado sem nada mais configurado permite que qualquer pessoa que alcance a porta leia, insira, atualize e exclua todas as tabelas do schema. Em um laptop, isso é conveniente. Em qualquer outro lugar, mude quatro coisas antes de habilitá-lo:
Depois, sirva-o por HTTPS definindo ssl_cert e ssl_key. Não existe uma configuração de endereço de bind, e o listener vincula todas as interfaces a partir do momento em que inicia, então bloqueie a porta no firewall e deixe somente um proxy reverso alcançá-la.

Solução de Problemas

Veja também