Database Directive Specification

// Forbidden to use the following options (rely on default code generation configuration)
option java_package = "...";
option java_multiple_files = true;
option go_package = "...";

// Forbidden to reference API layer messages
import "com/example/api/user/api.proto";  // Wrong!
import "com/example/api/order/request.proto";  // Wrong!

// Allow referencing constant layer (infra/)
import "com/example/infra/settings/user_constant.proto";

// Allow referencing other domain entities
import "com/example/domain/entities/order.proto";

message UserEntity {
  UserStatusEnum status = 1;  // Enums can be shared
  OrderEntity order = 2;  // Domain internal reference
}

import "apihug/protobuf/domain/annotations.proto";

extend google.protobuf.MessageOptions {
  Table table = 1772;
}

extend google.protobuf.FieldOptions {
  Column column = 1773;
}

message EntityName {
  option (hope.persistence.table) = {
    name: "TableName";
    description: "Table description";
    // Other configurations...
  };
}

string field_name = sequence [(hope.persistence.column) = {
  name: "ColumnName";
  description: "Column description";
  nullable: false;
  type: VARCHAR;
}];

syntax = "proto3";
package com.example.pet.domain;

import "apihug/protobuf/domain/annotations.proto";

message Category {
  option (hope.persistence.table) = {
    name: "CATEGORY",
    description: "Pet category",
    wires: [IDENTIFIABLE]
  };

  string name = 1 [(hope.persistence.column) = {
    name: "NAME",
    description: "Category name",
    nullable: false,
    length: 32,
    unique: true,
    type: VARCHAR
  }];
}

unique_constraints: {
  name: "UK_PET_NAME_CATEGORY",
  column_list: ["name", "category"]
}

indexes: {
  name: "IDX_PET_NAME",
  column_list: ["name"]
}

indexes: {
  name: "IDX_CATEGORY_UNIQUE",
  column_list: ["category"],
  unique: true
}

wires: [IDENTIFIABLE]                          // Only primary key
wires: [IDENTIFIABLE, AUDITABLE, DELETABLE]    // Audit + logical delete
wires: [ALL]                                   // Full features
wires: [NONE]                                  // Fully custom

views: [{
  name: "PetView",
  description: "Pet list view",
  includes: ["id", "name", "category", "size"]
}]

views: [{
  name: "PetDetailView",
  description: "Pet detail view (with category info)",
  includes: ["id", "name", "category"],
  references: [{
    entity: "Category",
    includes: ["description"],
    join_type: INNER,
    left_field: "category",
    right_field: "name"
  }]
}]

liquibase: {
  version: 1,
  comment: "MySQL special index",
  dbms: [MYSQL],
  sql: [
    "CREATE FULLTEXT INDEX idx_pet_name_ft ON PET(name)"
  ]
}

liquibase: {
  version: 2,
  comment: "Partitioned table for non-H2 databases",
  dbms: [H2],
  negative: true,
  sql: [
    "ALTER TABLE PET PARTITION BY RANGE (id)"
  ]
}

com.example.enumeration.Size size = 1 [(hope.persistence.column) = {
  name: "SIZE",
  enum_type: STRING,
  type: VARCHAR,
  length: 32
}];

int64 id = 1 [(hope.persistence.column) = {
  name: "ID",
  id: true,
  nullable: false,
  generated_value: {
    strategy: UUID
  }
}];

string status = 5 [(hope.persistence.column) = {
  name: "STATUS",
  default_value: "ACTIVE"
}];

string full_name = 10 [(hope.persistence.column) = {
  transient: true
}];

nullable: "false"  // String, wrong!
unique: "true"     // String, wrong!

nullable: false  // bool type
unique: true     // bool type

length: {value: 32}  // Old syntax!
precision: {value: 10}

length: 32  // uint32 type
precision: 10
scale: 2

syntax = "proto3";
package com.example.pet.domain;

import "domain/annotations.proto";
import "com/example/pet/enumeration/constants.proto";

message Pet {
  option (hope.persistence.table) = {
    name: "PET",
    description: "Pet information table",

    unique_constraints: {
      name: "UK_PET_NAME_CATEGORY",
      column_list: ["name", "category"]
    },

    indexes: {
      name: "IDX_PET_NAME",
      column_list: ["name"]
    },

    wires: [IDENTIFIABLE, AUDITABLE, DELETABLE]
  };

  string name = 1 [(hope.persistence.column) = {
    name: "NAME",
    description: "Pet name",
    nullable: false,
    length: 32,
    type: VARCHAR
  }];

  string category = 3 [(hope.persistence.column) = {
    name: "CATEGORY",
    description: "Category (associated CATEGORY#NAME)",
    nullable: false,
    length: 32,
    type: VARCHAR
  }];

  com.example.pet.enumeration.Size size = 4 [(hope.persistence.column) = {
    name: "SIZE",
    description: "Pet size",
    nullable: false,
    enum_type: STRING,
    type: VARCHAR,
    length: 32
  }];

  double weight = 5 [(hope.persistence.column) = {
    name: "WEIGHT",
    description: "Pet weight(kg)",
    nullable: false,
    type: DOUBLE
  }];
}

syntax = "proto3";
package com.example.order.domain;

import "domain/annotations.proto";
import "com/example/order/enumeration/constants.proto";

message Order {
  option (hope.persistence.table) = {
    name: "USER_ORDER",
    description: "Order table",

    indexes: {
      name: "IDX_ORDER_USER",
      column_list: ["user_id"]
    },
    indexes: {
      name: "IDX_ORDER_STATUS",
      column_list: ["status"]
    },

    wires: [ALL]
  };

  int64 id = 1 [(hope.persistence.column) = {
    name: "ID",
    description: "Order ID",
    id: true,
    nullable: false,
    generated_value: {
      strategy: UUID
    }
  }];

  int64 user_id = 2 [(hope.persistence.column) = {
    name: "USER_ID",
    description: "User ID",
    nullable: false,
    searchable: true,
    type: BIGINT
  }];

  com.example.order.enumeration.OrderStatus status = 3 [(hope.persistence.column) = {
    name: "STATUS",
    description: "Order status",
    nullable: false,
    enum_type: CODE,
    type: INTEGER
  }];

  double total_amount = 4 [(hope.persistence.column) = {
    name: "TOTAL_AMOUNT",
    description: "Order total amount",
    nullable: false,
    type: DECIMAL,
    precision: 10,
    scale: 2
  }];

  string remark = 5 [(hope.persistence.column) = {
    name: "REMARK",
    description: "Order remark",
    nullable: true,
    length: 500,
    type: VARCHAR
  }];

  string user_name = 10 [(hope.persistence.column) = {
    transient: true
  }];
}

nullable: "false"
length: {value: 32}
unique: "true"

nullable: false
length: 32
unique: true

Only need primary key → wires: [IDENTIFIABLE]
Need audit → wires: [IDENTIFIABLE, AUDITABLE]
Need logical delete → wires: [IDENTIFIABLE, DELETABLE]
Multi-tenant → wires: [IDENTIFIABLE, TENANTABLE]
Full features → wires: [ALL]
Fully custom → wires: [NONE]

Short string (<255) → VARCHAR + length
Long text → CLOB
Integer primary key → BIGINT
UUID primary key → VARCHAR(36) or framework handling
Amount → DECIMAL(10,2)
Date → DATE / TIMESTAMP
Boolean → BOOLEAN
Enum → VARCHAR + enum_type:STRING

syntax = "proto3";
package your_package;

import "domain/annotations.proto";

message EntityName {
  option (hope.persistence.table) = {
    name: "TABLE_NAME",
    description: "Description",
    wires: [IDENTIFIABLE]
  };

  field_type field_name = sequence [(hope.persistence.column) = {
    name: "COLUMN_NAME",
    description: "Description",
    nullable: false,
    type: SQL_TYPE
  }];
}

int64 id = 1 [(hope.persistence.column) = {
  name: "ID",
  id: true,
  nullable: false,
  generated_value: {
    strategy: UUID
  }
}];

double field_name = sequence [(hope.persistence.column) = {
  name: "COLUMN_NAME",
  nullable: false,
  type: DECIMAL,
  precision: 10,
  scale: 2
}];