db-read

library0.1.1jsnpmunverified

db-read is a read-only MCP server (Model Context Protocol) for coding agents to safely access PostgreSQL, MySQL, and MongoDB databases. Version 0.1.1 is the first stable release, offering unified configuration via .db-read.yml, CLI tools for validation and serving, and strict read-only guards: SQL queries are filtered for multi-statement and non-read commands, MongoDB aggregation blocks $out and $merge, and limits on rows/documents and timeouts are enforced. It supports environments (dev, staging, prod) and local or hosted connections. Compared to other MCP database tools, db-read uniquely supports three database kinds in one server with a focus on read-only safety for AI agents.

database ai-ml

npm install db-read

package ↗

INSTALL

IMPORT

SIG · DB-READ

db-read

databasejavascriptv0.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import dbRead from 'db-read'

✗ const dbRead = require('db-read')

ESM-only package, requires Node >= 20, no CommonJS export

validateConfig

✓ import { validateConfig } from 'db-read'

✗ const validateConfig = require('db-read').validateConfig

Named export available, but require() fails because package is ESM-only

serve

✓ import { serve } from 'db-read'

✗ import serve from 'db-read'

serve is a named export, not default; only default export is the main server class

type Config

✓ import type { Config } from 'db-read'

✗ import { Config } from 'db-read'

Config is a type-only export; use type import to avoid runtime errors in TypeScript

Shows basic setup with .db-read.yml config file, CLI commands for validation and serving, and a programmatic ESM import example.

// Create .db-read.yml file // version: 1 // defaultEnvironment: dev // environments: // dev: // connections: // my_pg: // kind: postgres // uri: postgresql://readonly:${DATABASE_PASSWORD}@localhost:5432/mydb // Then run CLI: // npx db-read validate-config --config .db-read.yml // npx db-read serve --env dev --config .db-read.yml // Example using the SDK programmatically (ESM): import { serve } from 'db-read'; import { readFile } from 'fs/promises'; const config = JSON.parse(await readFile('.db-read.yml', 'utf8')); // serve(config, { env: 'dev' });

Debug

Known issues

gotchaThe package is ESM-only. Using require() will throw a MODULE_NOT_FOUND error.

fix

Use import syntax or set \"type\": \"module\" in package.json.

affects: >=0.1.0

gotchaNode.js >= 20 is required. Older versions will fail to start.

fix

Upgrade Node to v20 or later.

affects: >=0.1.0

gotchaThe db-read.yml file is git-ignored by default. Forgetting to create it from the example will cause a 'Config file not found' error.

fix

Copy .db-read.example.yml to .db-read.yml and fill in credentials.

affects: >=0.1.0

gotchaEnvironment variables like ${DATABASE_PASSWORD} in the config URI are not expanded. You must hardcode the URI or use a tool like dotenv.

fix

Do not rely on ${VARIABLE} syntax; use direct values or a separate env management tool.

affects: >=0.1.0

breakingMongoDB aggregation pipeline rejects $out and $merge stages. Queries using these will return 'Forbidden aggregation stage' error.

fix

Remove $out and $merge stages from your aggregations.

affects: >=0.1.0

Errors

Common errors & fixes

Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'db-read'

Using require() on an ESM-only package.

fix

Change require('db-read') to import 'db-read'.

ValidationError: 'defaultEnvironment' is required

Missing environment section in .db-read.yml.

fix

Add 'defaultEnvironment: dev' (or another env) to the config.

MCP error: Timeout after 10000ms

Database query exceeded the default timeout.

fix

Increase timeoutMs in .db-read.yml under defaults or connection config.

Upgrade

Version history

0.1.1latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkrequiredCore MCP SDK for server implementation

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

packagedb-read ↗