Providers

Providers are how Bridge turns one CLI into a stable interface across different storage backends. Each provider is:

named in bridge.yaml
selected with --from <name>
responsible for connecting, listing, reading, and reporting health

Today, Bridge ships with two providers:

filesystem
postgres

How providers fit into Bridge

At runtime, Bridge:

loads bridge.yaml
resolves the provider by name
connects using that provider’s URI
calls list, read, or health
returns structured JSON

That means the command shape stays stable even when the backend changes.

bridge ls --from files
bridge ls --from db

bridge read README.md --from files
bridge read users/42 --from db

Capability model

The provider interface includes support for these capabilities:

read
list
write
delete
search

Current shipped providers are read-only:

Provider	Read	List	Write	Delete	Search
Filesystem	yes	yes	no	no	no
Postgres	yes	yes	no	no	no

Filesystem provider

Use the filesystem provider when you want Bridge to expose files and directories from a local project, docs folder, dataset, or generated output directory.

URI format

providers:
  files:
    type: filesystem
    uri: file://./docs

Bridge accepts:

relative paths like file://./docs
absolute paths like file:///Users/alice/project/docs

The target must exist and must be a directory when the provider connects.

What `ls` returns

bridge ls --from files lists the top-level contents of the configured root directory. Entries are returned as:

file
directory

Example:

[
  { "name": "README.md", "path": "README.md", "entry_type": "file" },
  { "name": "nested", "path": "nested", "entry_type": "directory" }
]

Current behavior worth knowing:

listing is not recursive
entries are sorted by name
file entries may include size and updated_at
directory entries do not include file size

What `read` returns

bridge read <path> --from files reads a file relative to the provider root. Examples:

bridge read README.md --from files
bridge read nested/deep.txt --from files

Bridge detects a content type from the file extension and then returns one of three data forms:

File kind	Returned `data.type`	Notes
UTF-8 text files	`text`	Includes Markdown, plain text, YAML, TOML, CSV, HTML, and similar text formats
Valid JSON files	`json`	Parsed into JSON before returning
Non-text or non-UTF-8 files	`binary`	Returned as base64-encoded content

Example text response:

{
  "data": {
    "type": "text",
    "content": "# Hello\n\nWorld\n"
  },
  "metadata": {
    "source": "filesystem",
    "path": "hello.md",
    "content_type": "text/markdown"
  }
}

Example binary response:

{
  "data": {
    "type": "binary",
    "content": "AAH//g==",
    "encoding": "base64"
  },
  "metadata": {
    "source": "filesystem",
    "path": "binary.bin",
    "content_type": "application/octet-stream"
  }
}

Security behavior

The filesystem provider enforces a root boundary. Once connected to a directory, Bridge:

canonicalizes the provider root
canonicalizes requested paths
rejects reads that escape the root directory

So a path like ../../etc/passwd is blocked instead of being resolved outside the configured provider.

Common filesystem errors

Directory does not exist

If the configured file:// URI points to a directory that does not exist, bridge connect can still write the config, but provider operations such as ls and read will fail when Bridge tries to connect.

Path is not a directory

A filesystem provider must point to a directory, not to a single file.

Path not found

If you try to read a file that does not exist under the configured root, Bridge returns a provider error.

Path traversal denied

If a requested path escapes the configured root, Bridge returns a path traversal error.

Postgres provider

Use the Postgres provider when you want agents to list tables and read rows from a PostgreSQL database through the same Bridge command surface.

URI format

providers:
  db:
    type: postgres
    uri: ${DATABASE_URL}

Bridge accepts:

postgres://...
postgresql://...

In practice, most teams should use an environment variable for credentials. Bridge can generate that config for you:

bridge connect DATABASE_URL --type postgres --as db

What `ls` returns

bridge ls --from db returns tables from the public schema. Example:

[
  { "name": "users", "path": "users", "entry_type": "table" },
  { "name": "orders", "path": "orders", "entry_type": "table" }
]

Current behavior worth knowing:

only the public schema is listed
entries are returned as table
table metadata does not currently include size or timestamps

What `read` returns

The Postgres provider supports two path shapes.

Read a whole table

bridge read users --from db

This returns a JSON array of rows.

Read a single row by primary key

bridge read users/42 --from db

This returns a single JSON object. Bridge detects the table’s primary key, casts the row identifier to the correct column type, and fetches that single row.

Important Postgres limitations today

The current implementation is intentionally conservative.

Reads only work against tables in the public schema
Table names must match [a-zA-Z_][a-zA-Z0-9_]*
Whole-table reads require a single-column primary key
Row reads also require a single-column primary key
Tables without a primary key are listed by ls but cannot be read with bridge read
Tables with composite primary keys are listed by ls but cannot be read with bridge read
Whole-table reads honor read --limit, and fall back to 100 rows when no explicit limit is provided

If you do not pass --limit, Bridge falls back to 100 rows for whole-table Postgres reads.

Type handling

Postgres rows are returned as JSON. Bridge currently handles common types such as:

integers
floats and numeric values
booleans
json and jsonb

For other column types, Bridge falls back to a string conversion where possible. If a value cannot be read in the expected way, it may be returned as null.

Metadata behavior

For Postgres reads, the metadata source is not just "postgres". Bridge stores a redacted version of the connection URI so the response can identify the backend without leaking passwords.

Security behavior

The Postgres provider is designed to keep table and row reads safe:

identifiers are validated before being used in SQL
identifiers are quoted when queries are built
row values are passed as bound parameters
connection URIs are redacted in user-facing metadata and status messages

Common Postgres errors

Table not found

If the requested table does not exist in the public schema, Bridge returns a provider error and suggests using bridge ls --from <provider> to see available tables.

Row not found

If the table exists but the requested primary key value does not, Bridge returns a provider error for that row path.

No primary key

If a table has no primary key, Bridge cannot safely support bridge read <table> or bridge read <table>/<id> for that table in the current implementation.

Composite primary key

If a table uses a composite primary key, Bridge currently refuses the read rather than guessing how the row path should be encoded.

Invalid identifier

Bridge rejects suspicious table names before they reach SQL. This blocks obvious injection attempts and keeps table paths constrained to simple identifiers.

Health checks

Both providers support bridge status.

The filesystem provider reports whether the configured directory exists
The Postgres provider runs a lightweight SELECT 1 health query and includes latency

Example:

{
  "providers": {
    "files": {
      "connected": true,
      "latency_ms": 0,
      "message": "Directory: /path/to/docs"
    },
    "db": {
      "connected": true,
      "latency_ms": 12,
      "message": "Connected to postgres://user:***@localhost:5432/mydb"
    }
  }
}

Planned providers

Bridge’s long-term direction is broader than the two providers available today. The current CLI roadmap calls out:

SQLite
S3
vector store providers such as Qdrant and Pinecone

The goal is to keep the agent-facing model the same even as the set of supported backends grows.

Next steps

Configuration

See how provider definitions live inside bridge.yaml.

CLI interface

See how provider reads and lists become structured JSON output.

CLI interface

Configuration

Commands

Security and errors

Providers

How providers fit into Bridge

Capability model

Filesystem provider

URI format

What `ls` returns

What `read` returns

Security behavior

Common filesystem errors

Postgres provider

URI format

What `ls` returns

What `read` returns

Read a whole table

Read a single row by primary key

Important Postgres limitations today

Type handling

Metadata behavior

Security behavior

Common Postgres errors

Health checks

Planned providers

Next steps

Configuration

CLI interface

CLI interface

Configuration

Providers

Commands

Security and errors

​How providers fit into Bridge

​Capability model

​Filesystem provider

​URI format

​What ls returns

​What read returns

​Security behavior

​Common filesystem errors

​Postgres provider

​URI format

​What ls returns

​What read returns

​Read a whole table

​Read a single row by primary key

​Important Postgres limitations today

​Type handling

​Metadata behavior

​Security behavior

​Common Postgres errors

​Health checks

​Planned providers

​Next steps

Configuration

CLI interface

How providers fit into Bridge

Capability model

Filesystem provider

URI format

What `ls` returns

What `read` returns

Security behavior

Common filesystem errors

Postgres provider

URI format

What `ls` returns

What `read` returns

Read a whole table

Read a single row by primary key

Important Postgres limitations today

Type handling

Metadata behavior

Security behavior

Common Postgres errors

Health checks

Planned providers

Next steps