From a767100f700c10cf44a4de0aaca02b4c00b8f31c Mon Sep 17 00:00:00 2001 From: 2160039878-cyber <285580214+2160039878-cyber@users.noreply.github.com> Date: Thu, 10 Sep 2026 08:07:07 +0800 Subject: [PATCH] docs: add Brazilian Portuguese and Russian READMEs (#594, #610) --- README.md | 4 +- README_es.md | 4 +- README_ja.md | 4 +- README_pt.md | 251 +++++++++++++++++++++++++++++++ README_ru.md | 254 ++++++++++++++++++++++++++++++++ README_zh.md | 4 +- scripts/readme-check.mjs | 2 +- tests/unit/readme-check.test.ts | 20 +++ 8 files changed, 538 insertions(+), 5 deletions(-) create mode 100644 README_pt.md create mode 100644 README_ru.md diff --git a/README.md b/README.md index 1e2740e90..0d842971b 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,9 @@ English · 简体中文 · 日本語 · - Español + Español · + Português · + Русский

diff --git a/README_es.md b/README_es.md index 46e8827cb..57ef4884c 100644 --- a/README_es.md +++ b/README_es.md @@ -12,7 +12,9 @@ English · 简体中文 · 日本語 · - Español + Español · + Português · + Русский

diff --git a/README_ja.md b/README_ja.md index babd5d8d0..89da434e9 100644 --- a/README_ja.md +++ b/README_ja.md @@ -12,7 +12,9 @@ English · 简体中文 · 日本語 · - Español + Español · + Português · + Русский

diff --git a/README_pt.md b/README_pt.md new file mode 100644 index 000000000..7b00d1cbb --- /dev/null +++ b/README_pt.md @@ -0,0 +1,251 @@ +

+ Logo do LibreDB Studio +

+ +

LibreDB Studio

+ +

+ Um editor de bancos de dados que você implanta junto dos seus dados. +

+ +

+ English · + 简体中文 · + 日本語 · + Español · + Português · + Русский +

+ +## Visão geral + +Você cria um banco na nuvem e, para consultá-lo, precisa abrir uma porta, configurar um +túnel SSH ou instalar um cliente em cada máquina da equipe. O LibreDB Studio permite +implantar o editor na mesma rede do banco e acessá-lo pelo navegador. Assim, você não +precisa expor o banco à internet só para usar o editor. + +O mesmo aplicativo atende a 16 mecanismos de banco de dados. Pode ser executado em um +contêiner, instalado como serviço, implantado no Kubernetes ou incorporado ao seu produto +pelo pacote `@libredb/studio`. Também há um aplicativo desktop para Linux. + +Todos os recursos fazem parte da versão MIT, incluindo SSO, controle de acesso por +papéis (RBAC), auditoria de consultas, diagramas ER e recursos de IA. Não há uma edição +empresarial que reserve essas funções. + +

+ Configuração de conexões no LibreDB Studio +

+ +## Início rápido + +Com **Node.js 24 ou superior**, no Linux, macOS ou Windows: + +```bash +npx @libredb/studio +``` + +O comando baixa a distribuição do servidor, verifica o arquivo e inicia o aplicativo. +Não é preciso clonar o repositório nem compilar o projeto. + +Se preferir **Docker**: + +```bash +docker run -p 3000:3000 ghcr.io/libredb/libredb-studio:latest +``` + +Abra [localhost:3000](http://localhost:3000). Na primeira execução, o aplicativo gera +as credenciais de administrador e mostra a senha no terminal ou no log do contêiner. +Use essas credenciais para entrar e adicionar uma conexão. + +Para acesso remoto, configure HTTPS. Se você precisar usar HTTP fora de `localhost`, +consulte a opção `AUTH_COOKIE_SECURE` e suas implicações na +[documentação de instalação](docs/DISTRIBUTION.md). + +## Recursos + +### Editor e exploração do schema + +- **Monaco**, o editor usado pelo VS Code, com sugestões de tabelas, colunas e palavras-chave SQL. +- **Paleta de comandos** em `Cmd/Ctrl+K` para localizar conexões, tabelas, consultas salvas e ações. +- **Várias abas**, cada uma com seu próprio estado de execução. +- **EXPLAIN visual** nos mecanismos que oferecem planos de execução. +- **Diagramas ER interativos**, com relacionamentos baseados em chaves estrangeiras reais, + busca de tabelas, minimapa e exportação em PNG ou SVG. +- **Comparação de schemas** e histórico de snapshots. A geração de SQL de migração depende + dos recursos do mecanismo; veja os detalhes na documentação de cada provedor. + +### Resultados e ferramentas de desenvolvimento + +- Grade virtualizada com filtros por coluna e exportação em CSV ou JSON. +- Edição de valores diretamente na grade quando o mecanismo permite atualizar linhas de uma tabela. +- Tabelas dinâmicas no navegador com `COUNT`, `SUM`, `AVG`, `MIN` e `MAX`, além de geração de SQL. +- Oito tipos de gráfico, com configurações que podem ser salvas e reutilizadas. +- Geração de interfaces TypeScript, schemas Zod, modelos Prisma, structs Go, dataclasses Python + e classes Java a partir do schema. +- Geração de dados de teste e de um dicionário de dados pesquisável, com exportação em Markdown. + +O mascaramento de valores é um recurso de **exibição no navegador**. Ele ajuda a evitar +exposição acidental durante uma demonstração, mas não substitui permissões no banco: +as respostas da API ainda contêm os valores completos para usuários autenticados. + +### IA opcional, com o modelo que você escolher + +O painel **Database Agent** fica ao lado do editor na aplicação independente. Você +informa um objetivo e inicia a execução; o agente consulta o banco e produz um relatório +com referências aos resultados usados. Os fluxos incluem **Investigate**, **Optimize** +e **Assess**. Assess usa contagens, sem enviar valores das colunas. + +- O modo **Agent** executa leituras apenas em **PostgreSQL, SQLite e DuckDB**. Ele usa uma + camada própria de execução somente leitura, com limites e auditoria. +- O modo **Plan** está disponível em todas as conexões. Usa o schema como contexto e + propõe instruções, mas não executa o SQL proposto. +- O agente não inicia tarefas sozinho, não escreve no editor e não aplica suas recomendações + automaticamente. As consultas que você executa no editor seguem outro caminho e não + herdam a política de somente leitura do agente. +- Gemini, OpenAI, Ollama e outros endpoints compatíveis com OpenAI podem fornecer o modelo. + O modo Agent exige suporte a chamadas de ferramentas; Plan não exige esse recurso. + +**Hospedar o Studio na sua rede não significa que todos os dados usados pela IA ficarão nela.** +Conforme o recurso, o endpoint configurado recebe o objetivo, SQL, schema e resultados de +leituras. O resumo do Data Profiler também inclui mínimos e máximos, que são valores reais +dos dados. Um modelo local permite manter esse processamento no ambiente que você controla. +Sem configuração `LLM_*`, o painel do agente não aparece; endpoints locais sem chave também +contam como modelos configurados. + +Leia o [guia do agente](docs/AGENT_GUIDE.md) e o +[fluxo de dados da IA](docs/AGENT_DATA_FLOW.md) antes de habilitá-lo com dados sensíveis. +O pacote incorporável `@libredb/studio` não inclui a interface do agente. + +### Autenticação e administração + +- Login local com e-mail e senha ou SSO por OIDC, configurado por variáveis de ambiente. +- Compatibilidade com provedores OIDC como Keycloak, Auth0, Okta e Azure AD. +- Authorization Code Flow com PKCE S256 e mapeamento de papéis a partir de claims. +- Painel de monitoramento para administradores, com consultas, sessões, armazenamento, + métricas e alertas. As informações disponíveis variam por mecanismo. +- Operações de manutenção específicas de cada banco, sem oferecer comandos que o provedor + não suporta. + +## Bancos de dados compatíveis + +A tabela lista os 16 mecanismos com suporte direto. Recursos como cancelamento, manutenção, +diagramas e métricas dependem do que cada banco disponibiliza. + +| Banco de dados | Driver ou protocolo | Recursos e limites | +| :--- | :--- | :--- | +| **PostgreSQL** | `pg` | Editor SQL, transações, EXPLAIN, exploração do schema e monitoramento. | +| **MySQL** | `mysql2` | Editor SQL, transações, EXPLAIN e monitoramento. | +| **Oracle** | `oracledb` em modo Thin | Editor SQL, exploração do schema, planos de execução e monitoramento. | +| **SQL Server** | `mssql` / `tedious` | Editor T-SQL, planos de execução e métricas; inclui Azure SQL. | +| **SQLite** | `bun:sqlite` / `node:sqlite` | Arquivo local ou banco em memória no servidor em que o Studio é executado. | +| **libSQL** | HTTP, protocolo Hrana | Banco remoto, incluindo Turso; autenticação por token. Manutenção limitada a REINDEX e PRAGMA integrity_check. | +| **DuckDB** | `@duckdb/node-api` | Arquivo local ou banco em memória, EXPLAIN em JSON e cancelamento. Sem lista de sessões ou log de consultas lentas; o arquivo só pode ser aberto por um processo do sistema operacional de cada vez. | +| **MongoDB** | `mongodb` | Editor JSON com operações find, aggregate, insert, update e delete em coleções. | +| **Couchbase** | HTTP, Query e API REST de administração | SQL++, EXPLAIN, exploração de buckets, scopes e coleções, inferência de colunas e manutenção. | +| **ClickHouse** | HTTP, interface SQL | Editor SQL, EXPLAIN em JSON, exploração do schema, estatísticas e cancelamento de consultas. | +| **Apache Druid** | HTTP, API SQL | SQL somente leitura, EXPLAIN e monitoramento; sem UPDATE, DELETE, CREATE TABLE ou operações de manutenção pelo editor. | +| **Elasticsearch** | HTTP, API SQL | SQL somente leitura, exploração de índices e campos e métricas do cluster. Sem EXPLAIN, manutenção ou paginação com OFFSET. | +| **OpenSearch** | HTTP, API SQL | Editor e explorador somente leitura; a paginação com LIMIT e OFFSET é suportada. | +| **Apache Trino** | HTTP, protocolo de cliente | SQL entre catálogos, EXPLAIN em JSON, monitoramento e cancelamento. Não declara chaves ou índices; a edição de linhas na grade fica desabilitada. Senhas exigem HTTPS. | +| **Apache Cassandra** | `cassandra-driver` | Editor CQL e explorador de keyspaces, com chaves de partição e clustering. Sem EXPLAIN, cancelamento ou manutenção; contagens de linhas e tamanhos não são exibidos. | +| **Redis** | `ioredis` | Editor de comandos, explorador de chaves e monitoramento baseado em INFO. | + +Outros produtos usam os mesmos protocolos desses provedores. Compatibilidade de protocolo +não garante todos os recursos do produto; consulte as medições e limitações na +[referência dos provedores](docs/providers/README.md#wire-compatible-engines). + +O túnel SSH funciona em conexões configuradas por host e porta. Conexões informadas apenas +por uma URI, assim como arquivos SQLite e DuckDB, não passam por esse túnel. As opções de +TLS e os requisitos de cada mecanismo estão descritos nos [guias dos provedores](docs/providers/README.md). + +## Instalação + +Há opções com e sem contêiner. Os comandos abaixo seguem a versão em inglês do README; +substitua `` pela versão do arquivo baixado quando necessário. + +| Canal | Comando ou download | Observações | +| :--- | :--- | :--- | +| **npx / npm** | `npx @libredb/studio` | Linux, macOS e Windows, com Node.js 24 ou superior. | +| **deb / rpm** | `sudo dpkg -i libredb-studio__amd64.deb` | Pacotes de servidor nos [Releases](https://github.com/libredb/libredb-studio/releases/latest), com runtime Node.js e serviço systemd. Para RPM, veja o guia de instalação. | +| **AppImage, desktop Linux** | `chmod +x libredb-studio-desktop--linux-x64.AppImage && ./libredb-studio-desktop--linux-x64.AppImage` | Janela nativa com servidor local em segundo plano, sem aba do navegador nem tela de login. | +| **Desktop, Debian/Ubuntu** | `sudo apt install ./libredb-studio-desktop-_amd64.deb` | Aplicativo com entrada no menu; é diferente do pacote de servidor. | +| **Snap** | `sudo snap install libredb-studio` | A senha inicial aparece em `sudo snap logs libredb-studio`. | +| **Arquivo tarball do servidor** | [Releases](https://github.com/libredb/libredb-studio/releases/latest) | Distribuição standalone para Linux e macOS; confira o arquivo SHA256SUMS e o [guia de distribuição](docs/DISTRIBUTION.md). | +| **Homebrew** | `brew trust libredb/tap && brew install libredb/tap/libredb-studio` | Homebrew 6 ou superior; a autorização inicial com `brew trust` é obrigatória. | +| **winget, Windows** | `winget install LibreDB.Studio` | Inclui o runtime Node.js. | +| **Docker** | `docker run -p 3000:3000 ghcr.io/libredb/libredb-studio:latest` | A senha inicial aparece no log do contêiner. | +| **Helm, Kubernetes** | `helm install libredb oci://ghcr.io/libredb/charts/libredb-studio` | As credenciais iniciais aparecem no log do Pod. | +| **Flatpak, desktop** | `flatpak --user remote-add --if-not-exists flatpark https://dl.flatpark.org/flatpark.flatpakrepo`
`flatpak --user install flatpark org.libredb.Studio` | Aplicativo em sandbox, distribuído pelo FlatPark; acesso a bancos por TCP, sem acesso ao sistema de arquivos. | + +Se `brew trust` não for reconhecido, execute `brew update`. Os pacotes deb/rpm de servidor +e os pacotes desktop são distribuições distintas: escolha o servidor para acesso pelo +navegador e o desktop para uma janela local. + +Os arquivos standalone usam o nome +`libredb-studio-standalone---.tar.gz`. O comando `npx` pode baixar e +iniciar a distribuição correspondente automaticamente. Para instalação manual, configuração, +uso com systemd e verificação de arquivos, consulte [DISTRIBUTION.md](docs/DISTRIBUTION.md). + +Também há modelos de implantação para plataformas como Railway, Dokploy, CapRover, Sealos, +Render, Fly.io e Koyeb. A lista e o estado de cada canal ficam em [CHANNELS.md](docs/CHANNELS.md). + +### Incorporar ao seu produto + +```bash +npm i @libredb/studio +``` + +O pacote permite incorporar o editor ao aplicativo que já gerencia os bancos dos seus usuários. +Veja o [guia de integração no README em inglês](README.md#embedding-in-your-own-app-libredbstudio) e confira a +[política de segurança](docs/SECURITY.md) ao configurar a aplicação que o hospeda. + +## Segurança + +O Studio executa as consultas com as permissões da conexão configurada. Restrinja essas +permissões ao necessário, proteja o acesso à aplicação e use TLS no acesso remoto. +Mascaramento visual, análise de consultas por IA e o modo somente leitura do agente têm +escopos diferentes; nenhum deles transforma todas as consultas do editor em operações +somente leitura. + +A [documentação de segurança](docs/SECURITY.md) descreve autenticação, cabeçalhos HTTP, +armazenamento de credenciais e os limites dessas proteções. Para relatar uma vulnerabilidade, +siga [SECURITY.md](SECURITY.md). + +## Testes e qualidade + +O projeto tem testes unitários, de API, de integração, de hooks, de componentes e E2E. +A CI exige **100% de cobertura de linhas**. Para executar os testes, use os scripts do projeto: + +```bash +bun run test +bun run test:coverage +bun run coverage:check +bun run readme:check +``` + +Use `bun run test`, não o comando direto `bun test`: os testes de componentes dependem +dos grupos isolados configurados pelo projeto. A suíte local também precisa de Helm e da +dependência PostgreSQL do chart; consulte os pré-requisitos em [CONTRIBUTING.md](CONTRIBUTING.md). + +## Documentação + +Os guias detalhados estão em inglês: + +- [Arquitetura](docs/ARCHITECTURE.md) e [API](docs/API_DOCS.md). +- [Provedores de banco de dados](docs/DATABASE_PROVIDERS.md) e [referências por mecanismo](docs/providers/README.md). +- [OIDC](docs/OIDC.md), [armazenamento](docs/STORAGE.md) e [Helm Chart](docs/HELM_CHART.md). +- [Guia do agente](docs/AGENT_GUIDE.md) e [dados enviados aos modelos](docs/AGENT_DATA_FLOW.md). + +## Como contribuir + +Leia [CONTRIBUTING.md](CONTRIBUTING.md), escolha uma issue e comente nela antes de começar. +Issues, PRs, código e documentação técnica devem ser escritos em inglês; READMEs traduzidos +são a exceção. Relacione o PR à issue e execute as verificações exigidas. + +Ao adicionar ou modificar um provedor, mantenha código, documentação e testes de integração +no mesmo PR. O [guia para adicionar provedores](docs/ADDING_A_PROVIDER.md) explica o processo. + +## Licença + +[MIT](LICENSE), sem CLA. O libredb-platform é o serviço pago de hospedagem, operação +multitenant, cobrança e suporte. Os recursos do Studio permanecem na versão MIT. diff --git a/README_ru.md b/README_ru.md new file mode 100644 index 000000000..b8c01a897 --- /dev/null +++ b/README_ru.md @@ -0,0 +1,254 @@ +

+ Логотип LibreDB Studio +

+ +

LibreDB Studio

+ +

+ Редактор баз данных, который разворачивается рядом с вашими данными. +

+ +

+ English · + 简体中文 · + 日本語 · + Español · + Português · + Русский +

+ +## Что это + +LibreDB Studio — редактор баз данных с веб-интерфейсом. Его можно развернуть в той же +сети, где работают базы: в контейнере, как системную службу, в Kubernetes или внутри +собственного приложения через пакет `@libredb/studio`. Открывать порт самой СУБД в +интернет ради доступа к редактору не требуется. + +Браузер работает как тонкий клиент; соединения с СУБД открывает сервер Studio. +Один интерфейс поддерживает 16 СУБД и движков запросов, поэтому отдельный толстый +клиент для каждой из них устанавливать не нужно. Для Linux есть и настольное приложение +с локальным сервером. + +SSO, управление доступом по ролям (RBAC), аудит запросов, ER-диаграммы и функции ИИ +входят в версию под лицензией MIT. Отдельной редакции с платным доступом к этим +возможностям нет. + +

+ Настройка подключений в LibreDB Studio +

+ +## Быстрый запуск + +**Без Docker**, с Node.js 24 или новее, на Linux, macOS или Windows: + +```bash +npx @libredb/studio +``` + +Команда скачивает готовый архив сервера, проверяет его и запускает приложение. +Клонировать репозиторий и собирать проект не нужно. Ниже также перечислены пакеты +deb/rpm, AppImage, Snap и отдельные архивы tarball. + +**Через Docker**: + +```bash +docker run -p 3000:3000 ghcr.io/libredb/libredb-studio:latest +``` + +Откройте [localhost:3000](http://localhost:3000). При первом запуске приложение создаёт +учётные данные администратора и выводит пароль в терминал или журнал контейнера. +Войдите с этими данными и добавьте подключение к базе. + +Для удалённого доступа настройте HTTPS. Если требуется HTTP с адресом, отличным от +`localhost`, сначала прочитайте об `AUTH_COOKIE_SECURE` и последствиях его изменения +в [руководстве по установке](docs/DISTRIBUTION.md). + +## Возможности + +### Редактор и схема базы + +- **Monaco**, редактор из VS Code, с автодополнением имён таблиц, столбцов и ключевых слов SQL. +- **Палитра команд** по `Cmd/Ctrl+K`: поиск таблиц, подключений, сохранённых запросов и действий. +- **Несколько вкладок** с независимым состоянием выполнения запросов. +- **Визуальный EXPLAIN**, если провайдер поддерживает планы выполнения. +- **Интерактивные ER-диаграммы** с реальными внешними ключами, поиском таблиц, мини-картой + и экспортом в PNG или SVG. +- **Сравнение схем** и история их снимков. Возможность сгенерировать SQL миграции зависит + от СУБД; ограничения описаны в справочнике соответствующего провайдера. + +### Результаты и инструменты разработки + +- Виртуализированная таблица результатов, фильтры по столбцам, экспорт в CSV и JSON. +- Редактирование значений прямо в таблице, если СУБД поддерживает обновление строк одной таблицы. +- Сводные таблицы в браузере: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX` и генерация SQL. +- Восемь типов диаграмм с сохранением настроек для повторного использования. +- Генерация интерфейсов TypeScript, схем Zod, моделей Prisma, структур Go, dataclass-классов + Python и классов Java по схеме базы. +- Генерация тестовых данных и словаря данных с поиском и экспортом в Markdown. + +Маскирование скрывает значения **только в интерфейсе браузера**. Это удобно при +демонстрации экрана, но не заменяет права доступа: ответы API для авторизованного +пользователя по-прежнему содержат исходные значения. + +### ИИ и передача данных модели + +В самостоятельном приложении рядом с редактором находится панель **Database Agent**. +Вы задаёте цель и запускаете задачу; агент читает данные и составляет отчёт со ссылками +на результаты, которыми обосновывает выводы. Среди сценариев — **Investigate**, +**Optimize** и **Assess**. В Assess используются только количества, без значений столбцов. + +- Режим **Agent** выполняет чтение только в **PostgreSQL, SQLite и DuckDB**. Для него + предусмотрен отдельный путь выполнения запросов с ограничениями и аудитом, + допускающий только чтение. +- Режим **Plan** доступен для всех подключений. Он использует схему как контекст и + предлагает SQL, но не выполняет предложенные запросы. +- Агент не запускает задачи сам, не меняет текст в редакторе и не применяет свои + рекомендации автоматически. Запросы, которые пользователь выполняет в редакторе, + идут другим путём и не подчиняются политике чтения агента. +- Можно подключить Gemini, OpenAI, Ollama или другой OpenAI-совместимый endpoint. + Режиму Agent нужна модель с поддержкой вызова инструментов; для Plan это не требуется. + +**Локальная установка Studio сама по себе не означает, что данные останутся в локальной сети.** +В зависимости от функции настроенный endpoint получает цель задачи, SQL, схему и результаты +чтения. При составлении описания Data Profiler модель получает минимумы и максимумы — реальные +значения из базы. Локальная модель позволяет выполнять эту обработку в своей инфраструктуре. +Без настроек `LLM_*` панель агента не отображается. Endpoint без API-ключа, например локальный +Ollama, тоже считается настроенной моделью. + +Точный состав запросов к модели описан в [документе о потоках данных ИИ](docs/AGENT_DATA_FLOW.md), +а порядок работы — в [руководстве агента](docs/AGENT_GUIDE.md). +Встраиваемый пакет `@libredb/studio` интерфейс агента не содержит. + +### Аутентификация и администрирование + +- Локальный вход по электронной почте и паролю либо SSO через OIDC; режим задаётся + переменными окружения. +- Поддерживаются стандартные OIDC-провайдеры, в том числе Keycloak, Auth0, Okta и Azure AD. +- Authorization Code Flow с PKCE S256; роли сопоставляются с claims провайдера. +- Панель мониторинга для администраторов: запросы, сеансы, хранилище, показатели + производительности и предупреждения. Набор доступных данных зависит от СУБД. +- Операции обслуживания предлагаются с учётом возможностей конкретного провайдера. + +## Поддерживаемые СУБД и движки запросов + +Это 16 непосредственно поддерживаемых систем. Планы выполнения, отмена запросов, +обслуживание и показатели мониторинга доступны там, где их предоставляет сама система. + +| Система | Драйвер или протокол | Возможности и ограничения | +| :--- | :--- | :--- | +| **PostgreSQL** | `pg` | SQL-редактор, транзакции, EXPLAIN, просмотр схемы и мониторинг. | +| **MySQL** | `mysql2` | SQL-редактор, транзакции, EXPLAIN и мониторинг. | +| **Oracle** | `oracledb`, режим Thin | SQL-редактор, просмотр схемы, планы выполнения и мониторинг. | +| **SQL Server** | `mssql` / `tedious` | Редактор T-SQL, планы выполнения и показатели мониторинга; поддерживается Azure SQL. | +| **SQLite** | `bun:sqlite` / `node:sqlite` | Локальный файл или база в памяти на сервере, где запущен Studio. | +| **libSQL** | HTTP, протокол Hrana | Удалённая база, включая Turso; аутентификация по токену. Из обслуживания доступны только REINDEX и PRAGMA integrity_check. | +| **DuckDB** | `@duckdb/node-api` | Локальный файл или база в памяти, EXPLAIN в JSON и отмена запросов. Нет списка сеансов и журнала медленных запросов; файл может быть открыт только одним процессом ОС одновременно. | +| **MongoDB** | `mongodb` | JSON-редактор: find, aggregate, insert, update и delete для коллекций. | +| **Couchbase** | HTTP, Query и управляющий REST API | SQL++, EXPLAIN, просмотр buckets, scopes и коллекций, определение столбцов и обслуживание. | +| **ClickHouse** | HTTP, SQL-интерфейс | SQL-редактор, EXPLAIN в JSON, просмотр схемы, статистика и отмена запросов. | +| **Apache Druid** | HTTP, SQL API | SQL только для чтения, EXPLAIN и мониторинг; нет UPDATE, DELETE, CREATE TABLE и операций обслуживания из редактора. | +| **Elasticsearch** | HTTP, SQL API | SQL только для чтения, просмотр индексов и полей, показатели кластера. Нет EXPLAIN, обслуживания и постраничной выборки через OFFSET. | +| **OpenSearch** | HTTP, SQL API | Редактор и просмотр схемы только для чтения; постраничная выборка через LIMIT и OFFSET поддерживается. | +| **Apache Trino** | HTTP, клиентский протокол | SQL по каталогам, EXPLAIN в JSON, мониторинг и отмена запросов. Нет объявленных ключей и индексов, редактирование строк в таблице отключено. Пароль можно передать только по HTTPS. | +| **Apache Cassandra** | `cassandra-driver` | CQL-редактор и просмотр keyspaces с ключами партиционирования и кластеризации. Нет EXPLAIN, отмены запросов и обслуживания; количество строк и размеры не показываются. | +| **Redis** | `ioredis` | Редактор команд, просмотр ключей и мониторинг на основе INFO. | + +Другие продукты могут подключаться через эти же протоколы. Такая совместимость не +означает поддержку всех функций. Проверенные версии и ограничения приведены в +[справочнике провайдеров](docs/providers/README.md#wire-compatible-engines). + +SSH-туннель применяется к подключениям с отдельно заданными host и port. Подключения, +заданные только строкой URI, а также локальные файлы SQLite и DuckDB через него не идут. +Параметры TLS и требования каждой СУБД описаны в [руководствах провайдеров](docs/providers/README.md). + +## Установка + +Docker необязателен. Ниже доступны как серверные пакеты, так и настольное приложение. +В командах с `` подставьте версию скачанного файла; сами команды совпадают +с английским README. + +| Канал | Команда или загрузка | Примечания | +| :--- | :--- | :--- | +| **npx / npm** | `npx @libredb/studio` | Linux, macOS и Windows; требуется Node.js 24 или новее. | +| **deb / rpm** | `sudo dpkg -i libredb-studio__amd64.deb` | Серверные пакеты в [Releases](https://github.com/libredb/libredb-studio/releases/latest), со своей средой Node.js и службой systemd. Установка RPM описана в руководстве. | +| **AppImage, Linux** | `chmod +x libredb-studio-desktop--linux-x64.AppImage && ./libredb-studio-desktop--linux-x64.AppImage` | Настольное приложение: отдельное окно и локальный сервер, без вкладки браузера и запроса входа. | +| **Настольное приложение, Debian/Ubuntu** | `sudo apt install ./libredb-studio-desktop-_amd64.deb` | Устанавливается в меню приложений; это не серверный пакет. | +| **Snap** | `sudo snap install libredb-studio` | Начальный пароль выводится в `sudo snap logs libredb-studio`. | +| **Отдельный архив tarball** | [Releases](https://github.com/libredb/libredb-studio/releases/latest) | Готовый standalone-сервер для Linux и macOS. Проверьте SHA256SUMS; подробности — в [руководстве](docs/DISTRIBUTION.md). | +| **Homebrew** | `brew trust libredb/tap && brew install libredb/tap/libredb-studio` | Нужен Homebrew 6 или новее; начальное разрешение через `brew trust` обязательно. | +| **winget, Windows** | `winget install LibreDB.Studio` | Среда Node.js входит в поставку. | +| **Docker** | `docker run -p 3000:3000 ghcr.io/libredb/libredb-studio:latest` | Готовый образ; начальный пароль выводится в журнал контейнера. | +| **Helm, Kubernetes** | `helm install libredb oci://ghcr.io/libredb/charts/libredb-studio` | Начальные учётные данные выводятся в журнал Pod. | +| **Flatpak** | `flatpak --user remote-add --if-not-exists flatpark https://dl.flatpark.org/flatpark.flatpakrepo`
`flatpak --user install flatpark org.libredb.Studio` | Настольное приложение из FlatPark в песочнице, без доступа к файловой системе; подключения к базам по TCP. | + +Если команда `brew trust` неизвестна, сначала выполните `brew update`. Не путайте два +вида пакетов deb: серверный пакет устанавливает службу для доступа через браузер, +а desktop-пакет — приложение с отдельным окном и локальным сервером. + +Архивы сервера называются +`libredb-studio-standalone---.tar.gz`. Команда `npx` сама скачивает и +запускает подходящий архив. Ручная установка, проверка файлов, настройка, запуск через +systemd и варианты тегов образов Docker описаны в [DISTRIBUTION.md](docs/DISTRIBUTION.md). + +Для Railway, Dokploy, CapRover, Sealos, Render, Fly.io, Koyeb и других платформ есть шаблоны +развёртывания. Полный список с состоянием каждого канала — в [CHANNELS.md](docs/CHANNELS.md). + +### Встраивание в своё приложение + +```bash +npm i @libredb/studio +``` + +Пакет позволяет встроить редактор туда, где пользователи уже управляют своими базами. +Пример интеграции есть в [английском README](README.md#embedding-in-your-own-app-libredbstudio). +При настройке приложения-хоста учитывайте [политику безопасности](docs/SECURITY.md). + +## Безопасность + +Studio выполняет запросы с правами настроенного подключения. Выдавайте этому подключению +только необходимые права, ограничивайте доступ к приложению и используйте TLS при удалённом +доступе. Маскирование в интерфейсе, анализ SQL моделью и ограничения агента решают разные +задачи. Для обычных запросов из редактора ограничения на запись задаются правами подключения. + +Аутентификация, HTTP-заголовки, хранение учётных данных и границы защиты описаны в +[документации по безопасности](docs/SECURITY.md). О найденной уязвимости сообщайте +по правилам [SECURITY.md](SECURITY.md). + +## Тесты и качество + +В проекте есть модульные, API-, интеграционные, компонентные и E2E-тесты, а также тесты React-хуков. +CI требует **100% покрытия строк**. Запускайте проверки через скрипты проекта: + +```bash +bun run test +bun run test:coverage +bun run coverage:check +bun run readme:check +``` + +Используйте `bun run test`, а не прямой вызов `bun test`: компонентные тесты зависят от +разделения на изолированные группы. Локально для полного набора тестов также нужны Helm и зависимость +PostgreSQL для chart; подготовка окружения описана в [CONTRIBUTING.md](CONTRIBUTING.md). + +## Документация + +Подробные руководства доступны на английском: + +- [Архитектура](docs/ARCHITECTURE.md) и [API](docs/API_DOCS.md). +- [Провайдеры баз данных](docs/DATABASE_PROVIDERS.md) и [справочник по СУБД](docs/providers/README.md). +- [OIDC](docs/OIDC.md), [хранилище](docs/STORAGE.md) и [Helm Chart](docs/HELM_CHART.md). +- [Руководство агента](docs/AGENT_GUIDE.md) и [передача данных модели](docs/AGENT_DATA_FLOW.md). + +## Участие в разработке + +Прочитайте [CONTRIBUTING.md](CONTRIBUTING.md), выберите issue и отметьтесь в комментариях +до начала работы. Issues, PR, код и техническая документация должны быть на английском; +переводы README — исключение. Укажите issue в PR и выполните обязательные проверки. + +При изменении провайдера его код, документация и интеграционные тесты обновляются в одном +PR. Порядок добавления СУБД описан в [руководстве для новых провайдеров](docs/ADDING_A_PROVIDER.md). + +## Лицензия + +[MIT](LICENSE), без CLA. Платный libredb-platform предоставляет хостинг, эксплуатацию +многопользовательской платформы, биллинг и поддержку. Возможности Studio остаются в MIT-версии. diff --git a/README_zh.md b/README_zh.md index 28bcac240..f27da8d02 100644 --- a/README_zh.md +++ b/README_zh.md @@ -12,7 +12,9 @@ English · 简体中文 · 日本語 · - Español + Español · + Português · + Русский

diff --git a/scripts/readme-check.mjs b/scripts/readme-check.mjs index 323776845..96d7895e0 100644 --- a/scripts/readme-check.mjs +++ b/scripts/readme-check.mjs @@ -31,7 +31,7 @@ import path from "node:path"; import { fileURLToPath } from "node:url"; const CANONICAL = "README.md"; -const LOCALIZED = ["README_zh.md", "README_ja.md", "README_es.md"]; +const LOCALIZED = ["README_zh.md", "README_ja.md", "README_es.md", "README_pt.md", "README_ru.md"]; /** Splits a markdown row into trimmed cells, dropping the leading/trailing empties. */ function cells(line) { diff --git a/tests/unit/readme-check.test.ts b/tests/unit/readme-check.test.ts index 200e929b2..c30fb0916 100644 --- a/tests/unit/readme-check.test.ts +++ b/tests/unit/readme-check.test.ts @@ -204,6 +204,26 @@ describe("checkReadmes", () => { }); describe("readme-check CLI", () => { + test.each(["README_pt.md", "README_ru.md"])("checks the engines in %s", (name) => { + const { exitCode, stderr } = runCLI({ + "README.md": readme(), + [name]: readme(["PostgreSQL", "MySQL"]), + }); + expect(exitCode).toBe(1); + expect(stderr).toContain(name); + expect(stderr).toContain("missing Redis"); + }); + + test.each(["README_pt.md", "README_ru.md"])("checks the install commands in %s", (name) => { + const { exitCode, stderr } = runCLI({ + "README.md": readme(), + [name]: readme(ENGINES, [COMMANDS[0], "snap install libredb-studio"]), + }); + expect(exitCode).toBe(1); + expect(stderr).toContain(name); + expect(stderr).toContain("does not appear verbatim"); + }); + test("passes on a consistent set and names the invariant it checked", () => { const { exitCode, stdout } = runCLI({ "README.md": readme(),