postgrebase

package module
v0.0.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 8, 2026 License: MIT Imports: 11 Imported by: 0

README

PostgreBase — AI原生的无代码API开发工具

PostgreBase 是 AI 原生的无代码 API 开发平台，基于 PocketBase 重构。内置 MCP (Model Context Protocol) 服务器，让 AI 工具（Claude、Cursor、Windsurf）直接操作你的数据。支持 PostgreSQL、MySQL、SQLite 三种数据库，提供即时 REST API + 实时订阅 + Admin UI，5分钟上线你的后端服务。

Features

  • Three Database Engines:
    • PostgreSQL (default) — production-grade concurrency, clustering, and complex queries.
    • MySQL — fully compatible via the mysql:// DSN prefix.
    • SQLite (pure Go, no CGO) — zero-dependency local development and testing via sqlite:// DSN or .db file path.
  • Cluster-Ready Architecture: No reliance on local database files means multiple instances can run behind a load balancer with a shared PostgreSQL/MySQL backend.
  • Hybrid Caching:
    • Redis Cache (--redisDsn) — distributed caching for cluster environments; SSE Realtime subscriptions synchronize across nodes via Redis Pub/Sub.
    • In-Memory Cache — automatic fallback to high-performance local memory caching when Redis is not configured.
  • MCP (Model Context Protocol) Server:
    • JSON-RPC 2.0 protocol enabling AI tools (Claude Desktop, Cursor, Windsurf) to interact with your data.
    • 8 built-in tools: list_collections, get_collection, list_records, get_record, create_record, update_record, delete_record, search_records.
    • Resources: postgrebase://collections, postgrebase://settings.
    • Three transport modes: SSE (HTTP), Streamable HTTP, and Stdio.
    • MCP-specific API tokens with expiration support, manageable from the Admin UI.
  • Zero External Dependencies for SQLite: Uses modernc.org/sqlite (pure Go transpilation of SQLite), builds with CGO_ENABLED=0.

Quick Start

Prerequisites
  • Go 1.26.2+
  • PostgreSQL, MySQL, or nothing (SQLite works out of the box)
Build
git clone https://github.com/zhenruyan/postgrebase.git
cd postgrebase
go build -o pb ./build/

For static builds (no CGO):

CGO_ENABLED=0 go build -o pb ./build/
Run
SQLite (Local Development)
# Using sqlite:// prefix
./pb serve --dataDsn "sqlite://./pb_data/dev.db"

# Or just pass a .db file path
./pb serve --dataDsn "./pb_data/dev.db"

./pb serve --dataDsn "postgresql://user:password@127.0.0.1:5432/dbname?sslmode=disable"
MySQL
./pb serve --dataDsn "mysql://user:password@tcp(127.0.0.1:3306)/dbname"
With Redis Cache
./pb serve --dataDsn "postgres://..." --redisDsn "redis://127.0.0.1:6379/0"
Docker
# Build the image
docker build -t postgrebase .

# Run with SQLite
docker run -p 8090:8090 -v pb_data:/pb/pb_data postgrebase serve --dataDsn "sqlite:///pb/pb_data/dev.db"

# Run with PostgreSQL
docker run -p 8090:8090 postgrebase serve --dataDsn "postgres://user:pass@host:5432/db?sslmode=disable"

# Run with Redis
docker run -p 8090:8090 postgrebase serve --dataDsn "postgres://..." --redisDsn "redis://host:6379/0"

On startup the server prints its endpoints:

├─ REST API: http://127.0.0.1:8090/api/
├─ MCP SSE:  http://127.0.0.1:8090/api/mcp/sse
└─ Admin UI: http://127.0.0.1:8090/_/

Configuration Flags

Flag Description Example
--dataDsn Database connection string sqlite://pb_data/data.db
--redisDsn (Optional) Redis connection string. Falls back to in-memory cache if omitted redis://localhost:6379/0
--dir Data directory for file uploads, backups, etc. ./pb_data
--encryptionEnv Environment variable name for settings encryption key PB_ENCRYPTION
--debug Enable debug mode with detailed logs (flag)
DSN Formats
Engine Format
PostgreSQL postgres://user:pass@host:port/db?sslmode=disable or postgresql://...
MySQL mysql://user:pass@tcp(host:port)/db
SQLite sqlite:///path/to/file.db, sqlite3://..., or simply ./file.db

MCP (Model Context Protocol)

PostgreBase includes a built-in MCP server that allows AI tools to interact with your data via a standardized JSON-RPC 2.0 protocol.

Transport Modes
SSE (Server-Sent Events) — HTTP

Available when running ./pb serve. Connect to:

GET  http://localhost:8090/api/mcp/sse      # SSE event stream
POST http://localhost:8090/api/mcp/message   # Send JSON-RPC requests
POST http://localhost:8090/api/mcp/stream    # Streamable HTTP (single request/response)
Stdio — CLI

Run the MCP server as a standalone process communicating over stdin/stdout:

./pb mcp --dataDsn "sqlite://./dev.db" --mcp-token "YOUR_TOKEN"

# Or disable auth (NOT recommended for production)
./pb mcp --dataDsn "sqlite://./dev.db" --mcp-no-auth
Flag Description
--mcp-token Admin JWT token or MCP-specific token for authentication
--mcp-no-auth Disable authentication (development only)
Claude Desktop Configuration
{
  "mcpServers": {
    "postgrebase": {
      "command": "/path/to/pb",
      "args": ["mcp", "--dataDsn", "sqlite:///path/to/dev.db", "--mcp-no-auth"]
    }
  }
}
MCP Tokens

For production use, create dedicated MCP tokens (prefixed with mcp_) from the Admin UI under Settings → MCP Tokens. These tokens:

  • Are separate from admin JWT tokens.
  • Can be revoked individually.
  • Support optional expiration dates.
  • Are shown in full only once at creation time.
Available Tools
Tool Description
list_collections List all collections
get_collection Get a collection's schema and settings
list_records List records with pagination, filtering, and sorting
get_record Get a single record by ID
create_record Create a new record
update_record Update an existing record
delete_record Delete a record
search_records Search records using PostgreBase filter expressions
Available Resources
URI Description
postgrebase://collections All collections with their schemas
postgrebase://settings Application settings (sanitized, no secrets)

Development

Building Admin UI

If you modify the Admin UI, rebuild the embedded assets before compiling the Go binary:

cd ui
npm install
npm run build
cd ..
go build -o pb ./build/
Project Structure
postgrebase/
├── build/           # Main server entry point (main.go)
├── core/            # Application logic, DB connection, caching
├── daos/            # Data access objects (CRUD operations)
├── models/          # Data models and schema definitions
├── apis/            # HTTP API handlers (REST + MCP routes)
├── mcp/             # MCP server: protocol, tools, resources, transports
├── migrations/      # Database migrations (Postgres/MySQL/SQLite)
├── cmd/             # CLI commands (serve, mcp, admin)
├── dbx/             # Database query builder (fork of ozzo-dbx)
├── tools/           # Shared utilities (security, types, search, etc.)
├── ui/              # Admin UI (Svelte + Vite)
├── vendor/          # Go dependencies (preserved for offline builds)
└── postgrebase.go  # Root package: CLI setup, config, bootstrap
Running Tests
go test ./tools/... ./models/... ./daos/...
Contributing
  1. Fork the repository.
  2. Create your feature branch (git checkout -b feature/amazing-feature).
  3. Commit your changes (git commit -m 'Add some amazing feature').
  4. Push to the branch (git push origin feature/amazing-feature).
  5. Open a Pull Request.

Credits

This project is a fork of PocketBase. Special thanks to Gani Georgiev for the original amazing work.

License

Licensed under the MIT license.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var Version = "(untracked)"

Version of PostgreBase

Functions

This section is empty.

Types

type Config 

type Config struct {
	// optional default values for the console flags
	DefaultDebug         bool
	DefaultDataDir       string // if not set, it will fallback to "./pb_data"
	DefaultDataDsn       string // if not set, it will fallback to "sqlite://pb_data/data.db"
	RedisDsn             string //redis://<user>:<pass>@localhost:6379/<db>
	DefaultEncryptionEnv string
	DisableVector        bool
	ClusterPeers         []string
	NodeAddr             string
	NodeID               string

	// hide the default console server info on app startup
	HideStartBanner bool

	// optional DB configurations
	DataMaxOpenConns int // default to core.DefaultDataMaxOpenConns
	DataMaxIdleConns int // default to core.DefaultDataMaxIdleConns
	LogsMaxOpenConns int // default to core.DefaultLogsMaxOpenConns
	LogsMaxIdleConns int // default to core.DefaultLogsMaxIdleConns
}

Config is the PostgreBase initialization config struct.

type PostgreBase added in v0.0.4 

type PostgreBase struct {

	// RootCmd is the main console command
	RootCmd *cobra.Command
	// contains filtered or unexported fields
}

PostgreBase defines a PostgreBase app launcher.

It implements core.App via embedding and all of the app interface methods could be accessed directly through the instance (eg. PostgreBase.DataDir()).

func New 

func New() *PostgreBase

New creates a new PostgreBase instance with the default configuration. Use [NewWithConfig()] if you want to provide a custom configuration.

Note that the application will not be initialized/bootstrapped yet, aka. DB connections, migrations, app settings, etc. will not be accessible. Everything will be initialized when [Start()] is executed. If you want to initialize the application before calling [Start()], then you'll have to manually call [Bootstrap()].

func NewWithConfig 

func NewWithConfig(config Config) *PostgreBase

NewWithConfig creates a new PostgreBase instance with the provided config.

Note that the application will not be initialized/bootstrapped yet, aka. DB connections, migrations, app settings, etc. will not be accessible. Everything will be initialized when [Start()] is executed. If you want to initialize the application before calling [Start()], then you'll have to manually call [Bootstrap()].

func (*PostgreBase) Execute added in v0.0.4 

func (pb *PostgreBase) Execute() error

Execute initializes the application (if not already) and executes the pb.RootCmd with graceful shutdown support.

This method differs from pb.Start() by not registering the default system commands!

func (*PostgreBase) Start added in v0.0.4 

func (pb *PostgreBase) Start() error

Start starts the application, aka. registers the default system commands (serve, migrate, version) and executes pb.RootCmd.

Source Files

View all Source files

Directories

Path Synopsis
Package apis implements the default PostgreBase api services and middlewares.
 Package apis implements the default PostgreBase api services and middlewares.
Package core is the backbone of PostgreBase.
 Package core is the backbone of PostgreBase.
Package daos handles common PostgreBase DB model manipulations.
 Package daos handles common PostgreBase DB model manipulations.
Package dbx provides a set of DB-agnostic and easy-to-use query building methods for relational databases.
 Package dbx provides a set of DB-agnostic and easy-to-use query building methods for relational databases.
Package models implements various services used for request data validation and applying changes to existing DB models through the app Dao.
 Package models implements various services used for request data validation and applying changes to existing DB models through the app Dao.
validators
Package validators implements custom shared PostgreBase validators.
 Package validators implements custom shared PostgreBase validators.
Package mails implements various helper methods for sending user and admin emails like forgotten password, verification, etc.
 Package mails implements various helper methods for sending user and admin emails like forgotten password, verification, etc.
templates
Package mcp implements the Model Context Protocol server for PostgreBase.
 Package mcp implements the Model Context Protocol server for PostgreBase.
Package migrations contains the system PostgreBase DB migrations.
 Package migrations contains the system PostgreBase DB migrations.
Package models implements all PostgreBase DB models and DTOs.
 Package models implements all PostgreBase DB models and DTOs.
schema
Package schema implements custom Schema and SchemaField datatypes for handling the Collection schema definitions.
 Package schema implements custom Schema and SchemaField datatypes for handling the Collection schema definitions.
settings
Package resolvers contains custom search.FieldResolver implementations.
 Package resolvers contains custom search.FieldResolver implementations.
Package tokens implements various user and admin tokens generation methods.
 Package tokens implements various user and admin tokens generation methods.
tools
archive
auth
cron
Package cron implements a crontab-like service to execute and schedule repeative tasks/jobs.
 Package cron implements a crontab-like service to execute and schedule repeative tasks/jobs.
dbutils
filesystem
hook
inflector
list
mailer
migrate
osutils
redis_cache
rest
routine
search
security
store
subscriptions
template
Package template is a thin wrapper around the standard html/template and text/template packages that implements a convenient registry to load and cache templates on the fly concurrently.
 Package template is a thin wrapper around the standard html/template and text/template packages that implements a convenient registry to load and cache templates on the fly concurrently.
tokenizer
Package tokenizer implements a rudimentary tokens parser of buffered io.Reader while respecting quotes and parenthesis boundaries.
 Package tokenizer implements a rudimentary tokens parser of buffered io.Reader while respecting quotes and parenthesis boundaries.
types
Package types implements some commonly used db serializable types like datetime, json, etc.
 Package types implements some commonly used db serializable types like datetime, json, etc.
Package ui handles the PostgreBase Admin frontend embedding.
 Package ui handles the PostgreBase Admin frontend embedding.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.