Skip to content

api.md

Latest commit

 

History

History
432 lines (311 loc) · 9.06 KB

api.md

File metadata and controls

432 lines (311 loc) · 9.06 KB
Raw

gRPC API Reference

The router exposes four gRPC services on port 50051 (default). All service and message definitions live in proto/dbrouter.proto.

Server reflection is always enabled — you do not need the .proto file locally to call the API.

# discover services
grpcurl -plaintext localhost:50051 list

# discover RPCs inside a service
grpcurl -plaintext localhost:50051 list dbrouter.PostgresService

# inspect a message type
grpcurl -plaintext localhost:50051 describe dbrouter.InsertDataRequest

HealthService

Check

Returns the connection status of all three backends in one call.

grpcurl -plaintext localhost:50051 dbrouter.HealthService/Check
{
  "overallHealthy": true,
  "postgres": { "status": "connected", "enabled": true, "host": "localhost", "database": "mydb" },
  "mongo":    { "status": "connected", "enabled": true, "database": "mydb" },
  "redis":    { "status": "connected", "enabled": true, "host": "localhost", "port": "6379" }
}

ConnectionStatus fields:

Field Description
status "connected", "disconnected", or "disabled"
enabled true if the backend is configured, false if disabled in config
host hostname (Postgres / Redis only)
port port string (Redis only)
database default database name (Postgres / Mongo)
error error message if status == "disconnected"

CheckPostgres / CheckMongo / CheckRedis

Same as Check but returns a single ConnectionStatus for one backend.

grpcurl -plaintext localhost:50051 dbrouter.HealthService/CheckPostgres

PostgresService

All RPCs that target a non-default database open a temporary connection for the duration of the call and close it afterwards.

ListDatabases

Lists all non-template databases.

grpcurl -plaintext localhost:50051 dbrouter.PostgresService/ListDatabases
{ "databases": ["postgres", "mydb", "analytics"] }

CreateDatabase

Creates a new PostgreSQL database. The name must match ^[a-zA-Z_][a-zA-Z0-9_]*$.

grpcurl -plaintext \
  -d '{"name":"analytics"}' \
  localhost:50051 dbrouter.PostgresService/CreateDatabase
{ "name": "analytics", "message": "Database created successfully" }

Runs outside any transaction (CREATE DATABASE cannot run inside one in PostgreSQL).

ListTables

Lists all user tables in the public schema of the given database.

grpcurl -plaintext -d '{"database":"mydb"}' \
  localhost:50051 dbrouter.PostgresService/ListTables
{ "database": "mydb", "tables": ["users", "orders", "products"] }

ExecuteQuery

Executes arbitrary SQL. SELECT-like statements return columns + rows; DML/DDL returns rows_affected.

# SELECT
grpcurl -plaintext \
  -d '{"query":"SELECT id, name FROM users LIMIT 5","database":"mydb"}' \
  localhost:50051 dbrouter.PostgresService/ExecuteQuery
{
  "columns": ["id", "name"],
  "rows": [
    {"fields": {"id": {"numberValue": 1}, "name": {"stringValue": "Alice"}}},
    {"fields": {"id": {"numberValue": 2}, "name": {"stringValue": "Bob"}}}
  ],
  "count": "2"
}
# DML
grpcurl -plaintext \
  -d '{"query":"UPDATE users SET active = true WHERE id = 1"}' \
  localhost:50051 dbrouter.PostgresService/ExecuteQuery
{ "rowsAffected": "1", "message": "Command executed successfully" }

Request fields:

Field Required Description
query yes SQL statement to execute
database no Target database; defaults to config database

Warning: This RPC executes arbitrary SQL. Never pass untrusted user input directly.

SelectData

Runs SELECT * FROM <table> LIMIT <limit> with identifier validation and quoting.

grpcurl -plaintext \
  -d '{"database":"mydb","table":"users","limit":10}' \
  localhost:50051 dbrouter.PostgresService/SelectData
{
  "database": "mydb",
  "table": "users",
  "data": [ {"fields": {"id": {"numberValue": 1}, "name": {"stringValue": "Alice"}}} ],
  "count": "1"
}
Field Required Description
database yes Database name
table yes Table name (alphanumeric + underscore only)
limit no Max rows (default 100, max 10 000)

InsertData

Inserts a row. If the table has an id column the new value is returned.

grpcurl -plaintext \
  -d '{
    "database": "mydb",
    "table": "users",
    "data": {
      "name":  {"stringValue": "Alice"},
      "email": {"stringValue": "alice@example.com"}
    }
  }' \
  localhost:50051 dbrouter.PostgresService/InsertData
{ "database": "mydb", "table": "users", "insertedId": "42" }

The data map uses google.protobuf.Value — use stringValue, numberValue, boolValue, or nullValue keys as appropriate.

UpdateData

Updates a row by id (WHERE id = $n).

grpcurl -plaintext \
  -d '{
    "database": "mydb",
    "table": "users",
    "id": "42",
    "data": { "name": {"stringValue": "Alicia"} }
  }' \
  localhost:50051 dbrouter.PostgresService/UpdateData
{ "database": "mydb", "table": "users", "id": "42", "rowsAffected": "1" }

DeleteData

Deletes a row by id.

grpcurl -plaintext \
  -d '{"database":"mydb","table":"users","id":"42"}' \
  localhost:50051 dbrouter.PostgresService/DeleteData
{ "database": "mydb", "table": "users", "id": "42", "rowsAffected": "1" }

MongoService

ListDatabases

grpcurl -plaintext localhost:50051 dbrouter.MongoService/ListDatabases
{ "databases": ["admin", "mydb", "logs"] }

ListCollections

grpcurl -plaintext -d '{"database":"mydb"}' \
  localhost:50051 dbrouter.MongoService/ListCollections
{ "database": "mydb", "collections": ["users", "events"] }

InsertDocument

Body is a google.protobuf.Struct (arbitrary JSON object).

grpcurl -plaintext \
  -d '{
    "database": "mydb",
    "collection": "events",
    "document": { "fields": { "type": {"stringValue": "login"}, "userId": {"numberValue": 1} } }
  }' \
  localhost:50051 dbrouter.MongoService/InsertDocument
{ "database": "mydb", "collection": "events", "insertedId": "65f1a2b3c4d5e6f7a8b9c0d1" }

FindDocuments

Returns all documents in a collection (no filter support yet — use ExecuteQuery via Postgres for filtered queries).

grpcurl -plaintext \
  -d '{"database":"mydb","collection":"events"}' \
  localhost:50051 dbrouter.MongoService/FindDocuments
{
  "database": "mydb",
  "collection": "events",
  "documents": [
    { "fields": { "_id": {"stringValue": "65f1…"}, "type": {"stringValue": "login"} } }
  ],
  "count": "1"
}

UpdateDocument

Updates a document by ObjectID using $set.

grpcurl -plaintext \
  -d '{
    "database": "mydb",
    "collection": "events",
    "id": "65f1a2b3c4d5e6f7a8b9c0d1",
    "update": { "fields": { "type": {"stringValue": "logout"} } }
  }' \
  localhost:50051 dbrouter.MongoService/UpdateDocument
{ "database": "mydb", "collection": "events", "matchedCount": "1", "modifiedCount": "1" }

DeleteDocument

Deletes a document by ObjectID.

grpcurl -plaintext \
  -d '{"database":"mydb","collection":"events","id":"65f1a2b3c4d5e6f7a8b9c0d1"}' \
  localhost:50051 dbrouter.MongoService/DeleteDocument
{ "database": "mydb", "collection": "events", "deletedCount": "1" }

RedisService

ListKeys

grpcurl -plaintext -d '{"pattern":"session:*"}' \
  localhost:50051 dbrouter.RedisService/ListKeys
{ "keys": ["session:abc", "session:xyz"], "count": "2" }

pattern defaults to * if omitted.

SetValue

grpcurl -plaintext \
  -d '{"key":"session:abc","value":"user:42","ttl":3600}' \
  localhost:50051 dbrouter.RedisService/SetValue
{ "key": "session:abc", "value": "user:42", "ttl": 3600 }

ttl is in seconds. Set to 0 (or omit) for no expiry.

GetValue

grpcurl -plaintext -d '{"key":"session:abc"}' \
  localhost:50051 dbrouter.RedisService/GetValue
{ "key": "session:abc", "value": "user:42", "ttl": 3540 }

Returns codes.NotFound if the key does not exist.

DeleteKey

grpcurl -plaintext -d '{"key":"session:abc"}' \
  localhost:50051 dbrouter.RedisService/DeleteKey
{ "key": "session:abc", "deleted": true }

Info

Returns raw INFO output and the key count for the current database.

grpcurl -plaintext localhost:50051 dbrouter.RedisService/Info
{ "dbSize": "42", "info": "# Server\nredis_version:7.2.4\n…" }

Error codes

gRPC code Meaning
OK Success
INVALID_ARGUMENT Bad input (invalid table name, missing field, etc.)
NOT_FOUND Key / document / row not found
UNAVAILABLE Backend not enabled in config, or connection refused
INTERNAL Database driver error