Vela PostgreSQL Skill for Agents and OpenClaw

A comprehensive PostgreSQL skill guide for Agents and OpenClaw, covering database management, Vela serverless integration, and best practices.

📖 How to Use This Skill: See USAGE-GUIDE.md for activation triggers, initialization workflow, and safety rules.

What is Vela?

Vela is a self-hostable, serverless Postgres development platform. Built on a high-performance distributed storage layer, it provides instant database branching, independent scaling of compute and storage, and enterprise-grade access control — all deployable in your own cloud. Enterprise-grade features and toolkit developers love in one product.

👉 The deployed documentation is available at https://docs.vela.run. 👉 The primary Vela repository is available at https://github.com/simplyblock/vela.

Repository Structure

vela-skill/
├── SKILL.md                  # Main skill guide with YAML frontmatter metadata
├── USAGE-GUIDE.md           # How to activate and use this skill (comprehensive guide)
├── README.md                # This file (project documentation)
└── sections/                # 19 detailed documentation sections
    ├── 01-schemas.md
    ├── 02-tables.md
    ├── 03-foreign-keys.md
    ├── 04-indexes.md
    ├── 05-partitioned-tables.md
    ├── 06-time-series.md
    ├── 07-views.md
    ├── 08-data-manipulation.md
    ├── 09-querying-data.md
    ├── 10-full-text-search.md
    ├── 11-vector-search.md
    ├── 12-functions-operators.md
    ├── 13-type-conversion.md
    ├── 14-row-level-security.md
    ├── 15-privileges.md
    ├── 16-vela-integration.md
    ├── 17-best-practices.md
    ├── 18-pagination.md
    └── 19-extensions.md

Overview

This skill provides comprehensive guidance for working with PostgreSQL databases, with specific support for:

• PostgreSQL Core Features - Tables, indexes, partitioning, views, data types
• Advanced Features - Full-text search, vector similarity search (pgvector), time-series data
• Vela Integration - Serverless PostgreSQL with PostgREST API
• Best Practices - Security, performance, and common mistakes to avoid

Quick Start

PostgreSQL Basics

-- Create a table
CREATE TABLE users (
    id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

-- Insert data
INSERT INTO users (email) VALUES ('user@example.com') RETURNING id;

-- Query data
SELECT * FROM users WHERE email LIKE '%@example.com';

Vela Connection

Recommended: Direct PostgreSQL Connection

postgresql://postgres:[PASSWORD]@db.{branchid}.demo.vela.run:{port}/postgres

⚠️ Important: Do not use TLS/SSL parameters. Vela does not support transport layer security for PostgreSQL connections.

Alternative: REST API (use PostgreSQL connections when possible)

https://{branchid}.demo.vela.run/rest

PostgreSQL Connection Example

psql "postgresql://postgres:[PASSWORD]@db.{branchid}.demo.vela.run:{port}/postgres" -c "SELECT * FROM users;"

REST API Example (Alternative)

# Query via REST
curl "https://{branchid}.demo.vela.run/rest/users?select=id,email&limit=10"

# Insert via REST
curl -X POST "https://{branchid}.demo.vela.run/rest/users" \
  -H "Content-Type: application/json" \
  -d '{"email": "new@example.com"}'

Documentation Sections

1. Schemas - Namespace organization
2. Tables - Creation, alteration, data types, constraints
3. Foreign Keys - Relationships and referential integrity
4. Indexes - B-tree, GIN, GiST, BRIN, partial, expression indexes
5. Partitioned Tables - Range, list, hash partitioning
6. Time-Series Data - Patterns for time-based data
7. Views - Regular and materialized views
8. Data Manipulation - INSERT, UPDATE, DELETE, RETURNING
9. Querying Data - SELECT, JOINs, CTEs, aggregation
10. Full-Text Search - tsvector, tsquery, ranking
11. Vector Similarity Search - pgvector extension, semantic search
12. Functions and Operators - Built-in PostgreSQL functions
13. Type Conversion - Casting between data types
14. Row-Level Security - Fine-grained access control
15. Privileges - User management and permissions
16. Vela Integration - Serverless PostgreSQL features
17. Best Practices - Common mistakes and how to avoid them
18. Pagination - Cursor vs offset pagination strategies
19. PostgreSQL Extensions - Available extensions on Vela (pgvector, PostGIS, TimescaleDB, etc.)

Key Features

PostgreSQL

• ✅ ACID compliance
• ✅ Rich data types (JSON, Arrays, UUIDs, Ranges)
• ✅ Advanced indexing (B-tree, GiST, GIN, BRIN, HNSW)
• ✅ Full-text search
• ✅ Partitioning
• ✅ Row-level security
• ✅ Extensions (pgvector, PostGIS)

Vela-Specific

• ✅ Serverless architecture
• ✅ PostgREST API (automatic REST endpoints)
• ✅ pgvector support (vector similarity search)
• ✅ Time-series optimization
• ✅ Database branching
• ✅ Full-text search via REST API

Best Practices

DO ✅

• Use GENERATED AS IDENTITY instead of SERIAL
• Use TIMESTAMP WITH TIME ZONE for timestamps
• Use NUMERIC for money
• Use TEXT or VARCHAR, avoid CHAR(n)
• Index foreign key columns
• Use parameterized queries
• Use EXISTS instead of COUNT(*) > 0
• Name all constraints explicitly

DON'T ❌

• Use SELECT *
• Store dates as strings
• Store passwords in plain text
• Use BETWEEN with timestamps
• Use NOT IN with nullable columns
• Grant excessive privileges
• Disable autovacuum
• Use string concatenation for SQL queries

Resources

• PostgreSQL Documentation
• PostgreSQL Don't Do This
• pgvector Extension
• PostgREST Documentation
• Vela Documentation

Contributing

This skill is maintained by Simplyblock for use with Coding Agents or OpenClaw and Vela.

License

MIT License - See SKILL.md for details

---

Version: 1.0.0
Last Updated: February 11, 2026
Author: Simplyblock

---

Vela Cloud (Recommended)

The easiest way to get started is through Vela Cloud.
Free tier available — no credit card required.

Get Started

Community

Find help, explore resources, or get involved with the Vela community.

Support & Contributions

• Open an Issue – Report bugs or suggest improvements
• Start a Discussion – Share feedback and feature ideas, ask questions, share ideas, and connect with other users
• Contribute Code – Submit pull requests following our contribution guidelines

We welcome contributions of all kinds — from documentation improvements and bug fixes to new features and integrations.