{"id":26058894,"url":"https://github.com/zackiles/postgres-proto-schema","last_synced_at":"2026-04-16T20:41:28.699Z","repository":{"id":270946787,"uuid":"911930347","full_name":"zackiles/postgres-proto-schema","owner":"zackiles","description":"A Protobuf (proto3 and buf v2) schema definition for PostgreSQL","archived":false,"fork":false,"pushed_at":"2025-02-16T09:47:26.000Z","size":405,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-07T17:16:11.559Z","etag":null,"topics":["buf","postgres","protobuf","schema"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zackiles.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-04T08:14:12.000Z","updated_at":"2025-02-18T14:54:35.000Z","dependencies_parsed_at":"2025-01-04T20:15:20.933Z","dependency_job_id":null,"html_url":"https://github.com/zackiles/postgres-proto-schema","commit_stats":null,"previous_names":["zackiles/postgres-proto-schema"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackiles%2Fpostgres-proto-schema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackiles%2Fpostgres-proto-schema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackiles%2Fpostgres-proto-schema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackiles%2Fpostgres-proto-schema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zackiles","download_url":"https://codeload.github.com/zackiles/postgres-proto-schema/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242552839,"owners_count":20148252,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["buf","postgres","protobuf","schema"],"created_at":"2025-03-08T12:40:52.213Z","updated_at":"2026-04-16T20:41:23.675Z","avatar_url":"https://github.com/zackiles.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Postgres Proto Schema\n\n[![Buf Schema Registry](https://img.shields.io/badge/buf.build-postgres--proto--schema-blue)](https://buf.build/zackiles/postgres-proto-schema)\n[![License](https://img.shields.io/github/license/zackiles/postgres-proto-schema)](LICENSE)\n\nA Protobuf (proto3 and buf v2) schema definition for PostgreSQL, enabling type-safe database schema generation through protocol buffers. This package provides comprehensive PostgreSQL type support, validation, and platform-specific deployment options.\n\n---\n\n## Table of Contents\n- [Postgres Proto Schema](#postgres-proto-schema)\n  - [Table of Contents](#table-of-contents)\n  - [Features](#features)\n  - [Installation](#installation)\n    - [1. Proto Files (Recommended)](#1-proto-files-recommended)\n    - [2. Pre-compiled SDKs](#2-pre-compiled-sdks)\n    - [3. Generate Your Own SDK](#3-generate-your-own-sdk)\n  - [Core Concepts](#core-concepts)\n    - [Type System](#type-system)\n    - [Type Options](#type-options)\n    - [Table Configuration](#table-configuration)\n    - [Column Options](#column-options)\n    - [Constraints](#constraints)\n    - [Composite Types](#composite-types)\n  - [Advanced Features](#advanced-features)\n    - [Built-in Patterns](#built-in-patterns)\n      - [Timestamps Pattern](#timestamps-pattern)\n      - [Audit Pattern](#audit-pattern)\n    - [Platform Support](#platform-support)\n    - [Validation](#validation)\n  - [Examples](#examples)\n    - [Basic Examples](#basic-examples)\n    - [Intermediate Examples](#intermediate-examples)\n    - [Advanced Examples](#advanced-examples)\n  - [Development](#development)\n    - [Project Structure](#project-structure)\n    - [Buf Commands](#buf-commands)\n  - [Contributing](#contributing)\n  - [License](#license)\n  - [Compatibility](#compatibility)\n  - [Contact](#contact)\n\n---\n\n## Features\n- Define PostgreSQL schemas using protocol buffers with:\n  - **Rich Type System**: Comprehensive PostgreSQL types with detailed configuration options\n  - **Table Configuration**: Names, schemas, indexes, constraints, RLS policies, partitioning\n  - **Column Configuration**: Type-specific options, constraints, collation\n  - **Platform Support**: Deployment options for major PostgreSQL platforms (RDS, Aurora, etc.)\n  - **Built-in Patterns**: Support for timestamps and audit tracking\n  - **Validation**: Built-in field validation using buf validate\n\n---\n\n## Installation\n\nThis package can be used in three ways:\n\n### 1. Proto Files (Recommended)\n\nUse the proto files directly through the Buf Schema Registry:\n\n```yaml\n# buf.yaml\nversion: v1\ndeps:\n  - buf.build/zackiles/postgres-proto-schema\n  - buf.build/bufbuild/protovalidate # Required for field validation rules\n```\n\nImport the proto files in your schema:\n```proto\nimport \"postgres_proto_schema/v1/schema.proto\";  // Main entrypoint\nimport \"buf/validate/validate.proto\";            // For validation rules\n```\n\nThe proto files are also available directly on [GitHub](https://github.com/zackiles/postgres-proto-schema/tree/main/proto/postgres_proto_schema).\n\n### 2. Pre-compiled SDKs\n\nWe provide pre-compiled code for Go and TypeScript and Javascript. At the moment we don't publish npm or go mods, but will soon! You can copy the files to your project source to include them manually for now:\n\n1. For the TypeScript and Javascript SDKs:\n```bash\n# Ran in your project workspace. Copies to ./src/postgres-proto-schema\ngit clone --depth 1 --filter=blob:none --sparse https://github.com/zackiles/postgres-proto-schema ./src/postgres-proto-schema \u0026\u0026 cd ./src/postgres-proto-schema \u0026\u0026 git sparse-checkout set gen/ts\n\n# Then import. Example:\n# import * as Schema from './src/postgres-proto-schema/gen/ts/schema_pb.js (or .ts/.d.ts)'\n# Node, you'll need to npm install @bufbuild/protobuf to use this SDK.\n```\n\n2. For the Go SDK:\n```bash\n# Ran in your project workspace. Copies to ./internal/postgres-proto-schema\ngit clone --depth 1 --filter=blob:none --sparse https://github.com/zackiles/postgres-proto-schema ./internal/postgres-proto-schema \u0026\u0026 cd ./internal/postgres-proto-schema \u0026\u0026 git sparse-checkout set gen/go\n\n# Then import it. Example:\n# import \"myproject/internal/postgres-proto-schema/v1\"\n```\n\n### 3. Generate Your Own SDK\n\nGenerate code for your preferred language using buf:\n\n```yaml\n# buf.gen.yaml\nversion: v1\nplugins:\n  - plugin: go\n    out: gen/go\n    opt: paths=source_relative\n  - plugin: typescript\n    out: gen/ts\n    opt: paths=source_relative\n```\n\nThen run:\n```bash\nbuf generate\n```\n\n---\n\n## Core Concepts\n\n### Type System\n\nThe package provides a comprehensive set of PostgreSQL types through the `Type` enum:\n\n| Category | Types |\n|----------|-------|\n| **Basic** | `TYPE_TEXT`, `TYPE_INTEGER`, `TYPE_BIGINT`, `TYPE_BOOLEAN`, `TYPE_TIMESTAMP`, `TYPE_TIMESTAMPTZ`, `TYPE_UUID`, `TYPE_JSONB`, `TYPE_VARCHAR`, `TYPE_NUMERIC` |\n| **Serial** | `TYPE_SERIAL`, `TYPE_BIGSERIAL`, `TYPE_SMALLSERIAL` |\n| **Temporal** | `TYPE_DATE`, `TYPE_TIME`, `TYPE_INTERVAL` |\n| **Binary** | `TYPE_BYTEA` |\n| **Network** | `TYPE_INET`, `TYPE_CIDR`, `TYPE_MACADDR` |\n| **Geometric** | `TYPE_POINT`, `TYPE_LINE`, `TYPE_POLYGON`, etc. |\n| **Full Text** | `TYPE_TSVECTOR`, `TYPE_TSQUERY` |\n\n### Type Options\n\nMany types support additional configuration through type-specific options:\n\n```proto\nmessage Column {\n  string email = 1 [(postgres_proto_schema.v1.column_options) = {\n    type: TYPE_VARCHAR\n    varchar: {\n      length: 255\n      collation: \"en_US\"\n    }\n  }];\n}\n```\n\n### Table Configuration\n\nTables support comprehensive PostgreSQL configuration:\n\n```proto\nmessage MyTable {\n  option (.postgres_proto_schema.v1.table_options) = {\n    table_name: \"my_table\"\n    schema: \"public\"\n    tablespace: \"fast_disk\"\n    is_unlogged: false\n    is_temporary: false\n    \n    // Storage parameters\n    storage_parameters: {\n      key: \"fillfactor\"\n      value: \"70\"\n    }\n\n    // Indexes\n    indexes: [{\n      name: \"my_index\"\n      columns: [\"column1\", \"column2\"]\n      index_method: INDEX_METHOD_BTREE\n      unique: true\n      where_clause: \"deleted_at IS NULL\"\n    }]\n\n    // Row Level Security\n    rls_policies: [{\n      name: \"tenant_isolation\"\n      using_expression: \"tenant_id = current_tenant_id()\"\n      with_check_expression: \"tenant_id = current_tenant_id()\"\n      role: \"authenticated\"\n    }]\n\n    // Partitioning\n    partitioning: {\n      method: PARTITION_METHOD_RANGE\n      keys: [\"created_at\"]\n    }\n  };\n}\n```\n\n### Column Options\n\nDifferent column types support specific configuration options:\n\n```proto\nmessage TypeExamples {\n  // VARCHAR with collation\n  string text = 1 [(postgres_proto_schema.v1.column_options) = {\n    type: TYPE_VARCHAR\n    varchar: {\n      length: 255\n      collation: \"en_US\"\n    }\n  }];\n\n  // NUMERIC with precision\n  double amount = 2 [(postgres_proto_schema.v1.column_options) = {\n    type: TYPE_NUMERIC\n    numeric: {\n      precision: 10\n      scale: 2\n    }\n  }];\n\n  // TIMESTAMP with timezone\n  string created_at = 3 [(postgres_proto_schema.v1.column_options) = {\n    type: TYPE_TIMESTAMPTZ\n    time: {\n      precision: 6\n    }\n  }];\n}\n```\n\n### Constraints\n\nAvailable constraint types:\n- `CONSTRAINT_TYPE_PRIMARY_KEY`\n- `CONSTRAINT_TYPE_NOT_NULL`\n- `CONSTRAINT_TYPE_UNIQUE`\n- `CONSTRAINT_TYPE_CHECK`\n- `CONSTRAINT_TYPE_FOREIGN_KEY`\n- `CONSTRAINT_TYPE_EXCLUSION`\n\nExample:\n```proto\nmessage Order {\n  int32 id = 1 [(postgres_proto_schema.v1.column_options) = {\n    constraints: [{\n      type: CONSTRAINT_TYPE_PRIMARY_KEY\n    }]\n  }];\n\n  int32 user_id = 2 [(postgres_proto_schema.v1.column_options) = {\n    constraints: [{\n      type: CONSTRAINT_TYPE_FOREIGN_KEY\n      foreign_key: {\n        foreign_table: \"users\"\n        foreign_column: \"id\"\n      }\n    }]\n  }];\n}\n```\n\n### Composite Types\n\nYou can mark messages as PostgreSQL composite types:\n\n```proto\nmessage Address {\n  option (.postgres_proto_schema.v1.is_composite_type) = true;\n\n  string street = 1 [(postgres_proto_schema.v1.column_options) = {\n    type: TYPE_VARCHAR\n    varchar: { length: 255 }\n  }];\n  string city = 2 [(postgres_proto_schema.v1.column_options) = {\n    type: TYPE_VARCHAR\n    varchar: { length: 100 }\n  }];\n}\n```\n\n---\n\n## Advanced Features\n\n### Built-in Patterns\n\nThe package provides two built-in patterns for common PostgreSQL table requirements:\n\n#### Timestamps Pattern\nAutomatically adds created_at, updated_at, and deleted_at columns:\n```proto\nmessage User {\n  option (.postgres_proto_schema.v1.timestamps) = {\n    track_created: true\n    track_updated: true\n    track_deleted: true\n  };\n}\n```\n\n#### Audit Pattern\nTracks record creators and updaters:\n```proto\nmessage User {\n  option (.postgres_proto_schema.v1.audit) = {\n    track_creator: true\n    track_updater: true\n    audit_schema: \"audit\"\n  };\n}\n```\n\n### Platform Support\n\nThe package includes built-in support for major PostgreSQL platforms through the `Platform` enum:\n\n| Category | Platforms |\n|----------|-----------|\n| **Cloud** | `PLATFORM_RDS`, `PLATFORM_AURORA`, `PLATFORM_CLOUD_SQL`, `PLATFORM_AZURE` |\n| **Managed** | `PLATFORM_HEROKU`, `PLATFORM_DIGITALOCEAN`, `PLATFORM_SUPABASE` |\n| **Enterprise** | `PLATFORM_ENTERPRISEDB`, `PLATFORM_TIMESCALEDB`, `PLATFORM_CRUNCHY` |\n| **Versions** | `PLATFORM_15`, `PLATFORM_16`, `PLATFORM_17` |\n\n### Validation\n\nThis package includes both compile-time and runtime validation through [protovalidate](https://buf.build/bufbuild/protovalidate/docs/main:buf.validate):\n\n```proto\nmessage User {\n  string email = 1 [(buf.validate.field).string.email = true];\n  \n  int32 age = 2 [(buf.validate.field).int32 = {\n    gte: 0\n    lte: 120\n  }];\n}\n```\n\nFor runtime validation in Go:\n```go\nimport \"github.com/bufbuild/protovalidate-go\"\n\nvalidator, err := protovalidate.New()\nif err != nil {\n    log.Fatal(err)\n}\n\nif err := validator.Validate(msg); err != nil {\n    log.Printf(\"validation failed: %v\", err)\n}\n```\n\nSee the [protovalidate documentation](https://buf.build/bufbuild/protovalidate/docs/main:buf.validate) for more validation options and language-specific usage.\n\n---\n\n## Examples\n\n### Basic Examples\n```proto\n// Simple table with basic columns\nmessage User {\n  option (.postgres_proto_schema.v1.table_options) = {\n    table_name: \"users\"\n    schema: \"public\"\n  };\n\n  int32 id = 1 [(postgres_proto_schema.v1.column_options) = {\n    type: TYPE_SERIAL\n    constraints: [{ type: CONSTRAINT_TYPE_PRIMARY_KEY }]\n  }];\n\n  string email = 2 [(postgres_proto_schema.v1.column_options) = {\n    type: TYPE_VARCHAR\n    varchar: { length: 255 }\n    constraints: [{ type: CONSTRAINT_TYPE_UNIQUE }]\n  }];\n}\n```\n\n### Intermediate Examples\n```proto\n// Multi-tenant table with RLS and timestamps\nmessage TenantResource {\n  option (.postgres_proto_schema.v1.table_options) = {\n    table_name: \"tenant_resources\"\n    schema: \"public\"\n    indexes: [{\n      name: \"tenant_resources_tenant_id_idx\"\n      columns: [\"tenant_id\"]\n    }]\n    rls_policies: [{\n      name: \"tenant_isolation\"\n      using_expression: \"tenant_id = current_tenant_id()\"\n    }]\n  };\n  \n  option (.postgres_proto_schema.v1.timestamps) = {\n    track_created: true\n    track_updated: true\n  };\n\n  string tenant_id = 1 [(postgres_proto_schema.v1.column_options) = {\n    type: TYPE_UUID\n    constraints: [{ type: CONSTRAINT_TYPE_NOT_NULL }]\n  }];\n}\n```\n\n### Advanced Examples\n```proto\n// Complex table with multiple features\nmessage Product {\n  option (.postgres_proto_schema.v1.table_options) = {\n    table_name: \"products\"\n    schema: \"inventory\"\n    partitioning: {\n      method: PARTITION_METHOD_RANGE\n      keys: [\"created_at\"]\n    }\n    indexes: [{\n      name: \"products_search_idx\"\n      columns: [\"name\", \"description\"]\n      index_method: INDEX_METHOD_GIN\n      expression: \"to_tsvector('english', name || ' ' || description)\"\n    }]\n  };\n\n  option (.postgres_proto_schema.v1.timestamps) = {\n    track_created: true\n    track_updated: true\n    track_deleted: true\n  };\n\n  option (.postgres_proto_schema.v1.audit) = {\n    track_creator: true\n    track_updater: true\n  };\n\n  // ... columns\n}\n```\n\n---\n\n## Development\n\n### Project Structure\n```\npostgres_proto_schema/\n├── proto/\n│   └── postgres_proto_schema/\n│       └── v1/\n│           ├── schema.proto    # Core schema definitions and extensions\n│           ├── table.proto     # Table-specific options and types\n│           ├── column.proto    # Column-specific options and types\n│           └── common.proto    # Shared types and enums\n├── gen/                        # Generated code directory\n│   ├── ts/                    # TypeScript generated code\n│   └── go/                    # Go generated code\n├── buf.yaml                   # Buf module definition\n└── buf.gen.yaml              # Code generation configuration\n```\n\n### Buf Commands\n1. **Lint the Protobuf files**:\n   ```bash\n   buf lint\n   ```\n2. **Build and validate the module**:\n   ```bash\n   buf build\n   ```\n3. **Push the module to the Buf Schema Registry**:\n   ```bash\n   buf push\n   ```\n\n---\n\n## Contributing\nContributions are welcome! To contribute:\n1. Fork the repository.\n2. Create a feature branch.\n3. Submit a pull request with a detailed description of your changes.\n\n---\n\n## License\nThis project is licensed under the MIT License. See `LICENSE` for details.\n\n---\n\n## Compatibility\n\n- PostgreSQL: 12+\n- Protocol Buffers: 3\n- Go: 1.21+\n- TypeScript: 4.5+\n\n---\n\n## Contact\nFor questions, suggestions, or support, open an issue on the GitHub repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzackiles%2Fpostgres-proto-schema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzackiles%2Fpostgres-proto-schema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzackiles%2Fpostgres-proto-schema/lists"}