Metadata-Version: 2.4
Name: lagun
Version: 0.1.77
Summary: A web-based MySQL/MariaDB GUI editor
Author-email: Anudeep Dhavaleswarapu <anudeepd2@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/anudeepd/lagun
Project-URL: Repository, https://github.com/anudeepd/lagun
Project-URL: Issues, https://github.com/anudeepd/lagun/issues
Keywords: mysql,mariadb,gui,web,database
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database :: Front-Ends
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.111.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: aiomysql>=0.2.0
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: click>=8.1.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: testcontainers[mysql]>=4.0; extra == "dev"
Provides-Extra: ldap
Requires-Dist: ldapgate>=0.1.24; extra == "ldap"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/anudeepd/lagun/main/assets/logo.svg" alt="Lagun" width="120"/>
</p>

<h1 align="center">Lagun</h1>

<p align="center">A minimal, web-based MySQL/MariaDB GUI editor. Install it, run it, use it.</p>

## Features

- **Web-based SQL editor** with syntax highlighting, autocompletion, and multi-tab support
- **Multi-statement execution** — run multiple statements at once, each result shown in its own sub-tab
- **Schema browser** — explore databases, tables, columns, and indexes; resizable sidebar
- **Schema management** — create, modify, and drop tables, columns, and indexes
- **In-line data editing** — edit cells, insert rows, delete rows directly in the grid
- **Import & export** — CSV and SQL formats with streaming for large datasets; export respects active column filters
- **Query history** — full SQL with word wrap, copy or load any entry back into the editor
- **Large write scripts** — normal Execute can run 25+ writes in one backend transaction with rollback
- **Bookmarks** — save and organize frequently used tables
- **Connection management** — import and export connection configs
- **Secure connections** — SSL/TLS, credentials stored in OS keyring, encrypted session backup
- **LDAP/AD authentication** — optional, via [ldapgate](https://github.com/anudeepd/ldapgate)

## Install

```bash
pip install lagun
```

## Usage

```bash
lagun serve
```

Opens the GUI in your browser. Connect to any MySQL or MariaDB database from there.

Options:

```
--host TEXT          Bind host. [default: 127.0.0.1]
--port INTEGER       Bind port. [default: 8080]
--no-open            Don't open the browser automatically.
--ldap-config PATH   Path to ldapgate YAML config to enable LDAP authentication.
```

## LDAP Authentication

Lagun can require users to log in via LDAP/AD before accessing the editor. This uses [ldapgate](https://github.com/anudeepd/ldapgate) as FastAPI middleware — no separate proxy process needed.

```bash
pip install 'lagun[ldap]'
lagun serve --ldap-config /path/to/ldapgate.yaml
```

For login bursts across at least 200 active users, size LDAPGate's bounded
connection pool and deadline in `/path/to/ldapgate.yaml`:

```yaml
ldap:
  timeout: 30
  pool_size: 16
```

### Shared connections and audit log

For LDAP deployments, an administrator can provide connections centrally and
limit each one to selected LDAP usernames:

```bash
export LAGUN_DBS_PASSWORD='database-password'
lagun serve --ldap-config /etc/lagun/ldap.yaml --connections-config /etc/lagun/connections.yaml
```

```yaml
connections:
  - id: dbs-production
    name: DBS Production
    host: mariadb.internal
    port: 3306
    username: shared_mariadb_user
    password_env: LAGUN_DBS_PASSWORD
    default: true
    selected_databases: [app, analytics]
    allowed_users: [alice, bob]
```

Listed users can use the connection but cannot edit it. Removing it in the UI
only hides it for that user. LDAP users may also create private connections;
those are visible only to their owner. Edit this file and restart Lagun to
change shared access. Set `selected_databases` to limit the visible schema
browser/search scope for a managed connection; omit it or use an empty list to
show all non-system schemas the database user can access.

LDAP API activity is recorded in Lagun's local `lagun.db`, not in MariaDB.
By default that database is `~/.lagun/lagun.db`; set `LAGUN_DB` to relocate the
whole local store (saved connections, settings, and audit events), for example
`LAGUN_DB=/var/lib/lagun/lagun.db`. Read it from the server with `lagun audit` and purge old entries with
`lagun audit purge --older-than 90`.

For direct local HTTP usage, set `proxy.secure_cookies: false` in the ldapgate
config. Keep `secure_cookies: true` in production and run Lagun behind HTTPS
with `trusted_proxies` configured so LDAPGate can honor `X-Forwarded-Proto`.

When LDAP is enabled, a logout button appears in the top-right corner of the tab bar.

### Admin console

LDAP administrators can open `/admin` to inspect saved connection metadata,
review recent API activity, monitor live workspaces, and manage the LDAP
allowlist without restarting Lagun. Enable the screen with an explicit
administrator allowlist:

```bash
lagun serve \
  --ldap-config /etc/lagun/ldap.yaml \
  --admin-user alice \
  --admin-user bob \
  --connections-config /etc/lagun/connections.yaml
```

`LAGUN_ADMIN_USERS=alice,bob` is equivalent to repeating `--admin-user`.
Administrator access is LDAP-only and separate from `connections.yaml`
`allowed_users`; connection inventory never returns stored database passwords.
Access policy remains owned by LDAPGate and the server-managed connections file.
The Users & policy view atomically updates `ldap.allowed_users`, creates a
mode-restricted backup, revokes removed users' active LDAP sessions, and applies
changes to new logins immediately. It requires `ldap.allowed_users` to be an
explicit YAML list; group-only LDAP policy must be changed in its source
configuration instead.

The admin console also includes a live workspace view: authenticated browser
clients publish tab identity heartbeats, and active normal or bulk executions
are shown with session, database, tab, state, duration, and complete SQL. Live
table tabs also report the current schema/data view, database, table, row limit,
partial all-column search, and applied `WHERE` clause; un-applied filter drafts
are not reported. Presence is process-local and expires after 45 seconds
without a heartbeat.

Query and API audit records preserve raw request targets, including query
parameters, and complete JSON request bodies. The audit form supports
case-insensitive partial matching across user, method, path, SQL, filters, and
raw JSON; Enter applies the current filters. Read-only admin polling is omitted
so user database activity remains visible. Expanded bodies wrap and scroll
vertically in the console.

See the [ldapgate README](https://github.com/anudeepd/ldapgate) for config file documentation.

## Concurrent Deployments

Lagun bounds database work so bursts from many browser tabs queue instead of
opening unlimited upstream connections. Defaults suit a single application
instance serving a small or medium internal team:

- `LAGUN_DB_POOL_MAX_SIZE=10` — connections per saved database session.
- `LAGUN_DB_GLOBAL_CONNECTION_LIMIT=100` — connections leased across all sessions.
- `LAGUN_DB_ACQUIRE_TIMEOUT_SECONDS=10` — maximum queue wait before HTTP 503.
- `LAGUN_DB_POOL_IDLE_SECONDS=900` — close pools unused for 15 minutes.
- `LAGUN_QUERY_MAX_RUNTIME_SECONDS=30` — normal query execution deadline.
- `LAGUN_SQLITE_BUSY_SECONDS=10` — local metadata/audit write wait.

Raise pool limits only after checking the connection ceilings and workload of
the target MySQL/MariaDB servers. Run one Lagun process per local `lagun.db`;
the SQLite metadata store and in-process query cancellation state are not
designed for shared multi-process deployment.

## Large Write Scripts

For large write scripts (25+ `INSERT`, `UPDATE`, or `DELETE` statements), Lagun
can send the entire script to the backend in one request from the normal Execute
button. The backend executes all statements in order inside one transaction and
rolls back on first failure.
Set `LAGUN_BULK_WRITE_THRESHOLD` or `VITE_LAGUN_BULK_WRITE_THRESHOLD` at
frontend build time to change the UI threshold.

See [docs/bulk-execution.md](docs/bulk-execution.md) for API details, limits,
admin configuration, and troubleshooting.

## Screenshots

<p align="center">
  <img src="https://raw.githubusercontent.com/anudeepd/lagun/main/assets/img_1.png" alt="SQL Editor" width="100%"/>
  <img src="https://raw.githubusercontent.com/anudeepd/lagun/main/assets/img_2.png" alt="Schema View" width="100%"/>
  <img src="https://raw.githubusercontent.com/anudeepd/lagun/main/assets/img_3.png" alt="Data View with Search" width="100%"/>
  <img src="https://raw.githubusercontent.com/anudeepd/lagun/main/assets/img_4.png" alt="Data View with Filter" width="100%"/>
</p>

## Development

Requires [uv](https://github.com/astral-sh/uv).

```bash
git clone https://github.com/anudeepd/lagun
cd lagun
uv sync
uv run lagun serve
```

## License

MIT
