# SQL Database Bridge

This local Codex plugin exposes configured SQL databases through a small MCP stdio server.
SQLite works with Python's standard library. SQL Server/MSSQL, PostgreSQL, and MySQL are optional adapters.

This repository is the open-source client/plugin. Account login, billing, entitlements, OAuth, and
hosted PostgreSQL remain on the SQL Bridge portal at https://sql-bridge.lovable.app.

## Install from source

Clone this repository and install the adapters into the same Python runtime that launches the MCP
server:

```powershell
python -m pip install -r .\requirements.txt
```

Microsoft SQL Server also requires Microsoft's ODBC Driver 17 or 18 installed on the desktop.
The plugin never installs drivers or packages automatically.

For a bundled local runtime, run the platform installer once from the plugin directory:

```powershell
.\install.ps1
```

On macOS or Linux:

```bash
./install.sh
```

The installer creates a local `.runtime` environment containing the Python adapters. The launcher
automatically uses it for MCP requests. The Windows release bundle can be built with
`.\build_windows_bundle.ps1`; it includes the Python adapters in a standalone executable. Microsoft
SQL Server's ODBC driver remains a separately installed Microsoft prerequisite.

## Execution modes

The Lovable app is the account, billing, entitlement, and hosted MCP control plane. Both execution
modes require the same authenticated Lovable account and active entitlement. Local desktop mode is
the default: SQL connections stay on the desktop, but every local SQL tool call is still gated by a
Lovable OAuth login and the hosted `get_account_access` check. Local mode is not an authorization bypass.

The hosted endpoint is baked into the plugin as the default:

```powershell
https://sql-bridge.lovable.app/mcp
```

Use `LOVABLE_MCP_URL` to override it for another deployment. To select the hosted advanced mode,
set `SQL_BRIDGE_MODE=remote` (or `hosted`) before starting the MCP process. Hosted mode exposes
Lovable's cloud PostgreSQL tools. Set `SQL_BRIDGE_MODE=local` only when you want to make the local
default explicit.

The first call to `login_platform` opens the SQL Database Bridge platform account login in a browser
(`login_lovable` remains a legacy alias).
The plugin reads the app's protected
resource metadata, follows its advertised Supabase Auth issuer, uses the issuer's
`/.well-known/oauth-authorization-server` metadata, registers a native client with DCR, and
completes PKCE login. `LOVABLE_OAUTH_ISSUER` is only an optional override. The bridge persists the
refresh token in the OS keyring when available, with Windows DPAPI as the secure fallback, so a new
MCP process reuses the linked account instead of reopening browser approval.

The current Lovable MCP manifest publishes eight tools: `echo`, `list_connections`,
`get_connection`, `test_connection`, `list_schemas`, `list_tables`, `describe_table`, and
`run_query`, plus the metadata-sync tools `upsert_connection` and `delete_connection`. The proxy discovers the live manifest after login and also advertises this known
surface during first-run login so MCP clients that cache `tools/list` can continue.

Hosted execution currently supports PostgreSQL. Lovable returns a clear unsupported-driver error
for MySQL, MSSQL, and SQLite; use the default local mode when the database is on the desktop or
when those drivers are required.

### Hosted query flow

1. Call `login_platform` once. The browser handles the platform/Google/email login; the plugin stores
   the resulting refresh token in the operating-system keyring and checks entitlement before SQL
   execution.
2. Call `list_connections` and choose a connection `id`. Connection metadata is RLS-scoped to the
   authenticated user and secrets never leave the hosted backend.
3. Use `test_connection`, `list_schemas`, `list_tables`, or `describe_table` as needed.
4. Call `run_query` with a UUID, SQL, optional parameters, and an optional row limit:

```json
{
  "connection_id": "3f2c...",
  "sql": "select id, email from users where created_at > $1 limit 50",
  "params": ["2026-01-01"],
  "row_limit": 1000
}
```

`run_query` is read-only, rejects multi-statement input, applies a statement timeout, and returns
bounded results with `columns`, `rows`, `rowCount`, `truncated`, and `duration_ms` in structured
content.

### Local connection metadata sync

In local mode, the database connection and password remain on the desktop. The
plugin synchronizes only non-secret metadata with Lovable:

- `connect_database` automatically calls `upsert_connection` and persists the returned UUID.
- `list_connections` and `sync_connections` pull remote metadata and push unsynced local metadata.
- Connections created elsewhere appear locally as `needs_credentials: true`; supply credentials
  locally with `connect_database` before using them.
- `delete_connection` removes the local connection and calls the hosted `delete_connection` tool.
- `close_connection` only closes the current session and leaves metadata available for later
  reattachment.

The local sync file is user-local and contains metadata only. It never stores passwords, secret
ciphertext, or credential-bearing connection strings. Local sync still requires `login_platform`
and an active platform entitlement.

## Configure databases

For environment-configured local connections, set `SQL_DATABASE_URLS` to a JSON object before
starting Codex, for example:

```powershell
$env:SQL_DATABASE_URLS = '{"main":"sqlite:///C:/data/app.db","analytics":"postgresql://user:password@localhost:5432/analytics"}'
```

You can use `SQL_DATABASE_URL` for one database, which is exposed as `default`.

Install optional drivers when needed:

```powershell
python -m pip install pyodbc "psycopg[binary]" pymysql
```

The command must target the same Python executable used by the MCP server. If the server reports
that `pyodbc` is missing, run `python -m pip install pyodbc` once in that runtime; the plugin does
not silently install packages or make network changes during a database connection.

For MSSQL, also install Microsoft ODBC Driver 18 or 17 for SQL Server on the desktop. The server
automatically prefers Driver 18 and falls back to Driver 17 when no explicit `driver` is supplied. The desktop
bridge can pass a connection directly to `connect_database`, so credentials do not need to be
stored in `SQL_DATABASE_URLS` or in the plugin files. Example SQL authentication profile:

```json
{
  "name": "mssql-main",
  "engine": "mssql",
  "server": "sql01.example.com",
  "port": 1433,
  "database": "Sales",
  "authentication": "sql",
  "username": "report_reader",
  "password": "<provided by the bridge>",
  "trust_server_certificate": false,
  "encrypt": true
}
```

For Windows authentication, omit username/password and use `"authentication": "windows"`.
The current Windows user running the MCP process is used by the ODBC driver. This requires the
Codex desktop process and the target SQL Server to support that user's Windows identity.

Runtime `connect_database` profiles are held only in memory for the MCP process. Call
`close_connection` when finished. A password passed in a tool call may still be visible to the
host application's logs or transcript, so the desktop bridge should apply its own authorization,
redaction, and confirmation policy before forwarding credentials.

In local mode, `list_connections`, `connect_database`, `list_tables`, `describe_table`,
`query_sql`, and `close_connection` return an authentication or account-access error until
`login_platform` succeeds and the hosted `get_account_access` check reports `entitled: true`.
Set `LOVABLE_ENTITLEMENT_TOOL` only when using a compatible deployment with a different tool name.

For a LocalDB connection, the bridge can send this compact profile. The connection name defaults
to `main`, the engine is inferred as MSSQL from `server`, and encryption defaults to off for LocalDB:

```json
{
  "server": "(localdb)\\MSSQLLocalDB",
  "database": "eMeditDb",
  "authentication": "windows"
}
```

The tool also accepts a nested `connection` object and aliases such as `host`, `database_name`,
`auth`, and `encryption`. If a LocalDB instance rejects encryption, the bridge retries once with
`Encrypt=no` by default; set `allow_localdb_encryption_fallback` to `false` to disable that behavior.

The default local server exposes `connect_database`, `list_connections`, `sync_connections`,
`delete_connection`, `list_tables`, `describe_table`, `query_sql`, and `close_connection`.
Read-only statements are the default. Set `SQL_ALLOW_WRITE=true` only for a database where
write access is intentional. `SQL_MAX_ROWS` limits returned rows and defaults to 500.

## Run the server directly

```powershell
$env:SQL_DATABASE_URL = 'sqlite:///C:/data/app.db'
python .\server.py
```

The `.mcp.json` file launches the same server from Codex with stdio transport.

## Codex preferences

The plugin declares only safe, non-secret preferences in its MCP environment. In Codex, open
`~/.codex/config.toml` from the settings page and add or adjust this server override:

```toml
[mcp_servers.sql-database-bridge]
env = {
  SQL_ALLOW_WRITE = "false",
  SQL_MAX_ROWS = "500",
  SQL_BRIDGE_MODE = "local",
  LOVABLE_MCP_URL = "https://sql-bridge.lovable.app/mcp",
}
```

Use `SQL_ALLOW_WRITE = "true"` only when write operations are intentional. The plugin does not
declare database URLs, usernames, passwords, OAuth tokens, or connection profiles as preferences.
Those remain local/secure and are supplied through the connection tools and platform login flow.