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 @@
+
+
+
+
+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.
+
+
+
+
+
+## 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
+
+
+ Редактор баз данных, который разворачивается рядом с вашими данными.
+
+
+
+ English ·
+ 简体中文 ·
+ 日本語 ·
+ Español ·
+ Português ·
+ Русский
+
+
+## Что это
+
+LibreDB Studio — редактор баз данных с веб-интерфейсом. Его можно развернуть в той же
+сети, где работают базы: в контейнере, как системную службу, в Kubernetes или внутри
+собственного приложения через пакет `@libredb/studio`. Открывать порт самой СУБД в
+интернет ради доступа к редактору не требуется.
+
+Браузер работает как тонкий клиент; соединения с СУБД открывает сервер Studio.
+Один интерфейс поддерживает 16 СУБД и движков запросов, поэтому отдельный толстый
+клиент для каждой из них устанавливать не нужно. Для Linux есть и настольное приложение
+с локальным сервером.
+
+SSO, управление доступом по ролям (RBAC), аудит запросов, ER-диаграммы и функции ИИ
+входят в версию под лицензией MIT. Отдельной редакции с платным доступом к этим
+возможностям нет.
+
+
+
+
+
+## Быстрый запуск
+
+**Без 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(),