Schema Config (reflexdb.yaml)

The reflexdb.yaml file controls which tables, columns, and relations are included in the compiled schema. It is applied at provision or rebuild time.

If no config is uploaded, all tables and all columns are included.

File format

version: 1

# Optional global row predicate
where: "deleted_at IS NULL"
where_columns: [deleted_at]

tables:
  - name: <table_name>
    alias: <api_name>               # optional — renames the table in the API
    columns: [col1, col2, ...]
    where: "active = 1"             # optional — per-table predicate override
    relations:
      include: [derived_name1, ...]
      exclude: [derived_name2, ...]
    reverse_relations:
      exclude: [derived_name3, ...]
    field_aliases:
      col_name: alias_name          # rename fields in the API
    field_notes:
      col_name: "Description"       # appear in the OpenAPI spec

Fields

`version`

version: 1

Must be 1. Required.

Tables

An array of table configurations. Tables not listed here are excluded from the schema entirely.

If tables is omitted, all tables are included with all columns and relations.

`tables[].name`

The MySQL table name. Required.

`tables[].columns`

columns: [id, name, email, created_at]

An allowlist of column names to include. Columns not listed are excluded from query results and the OpenAPI schema.

If omitted, all columns are included.

Relations

Controls which forward relations (foreign keys on this table) are exposed.

relations:
  include: [author, category]   # only expose these relations
  exclude: [internal_ref]       # expose all except these

include and exclude are mutually exclusive — use one or the other.

Derived relation names are derived from the FK column name by stripping a trailing _id:

FK column	Derived name
`author_id`	`author`
`category_id`	`category`
`user`	`user` (no `_id` to strip)

Use the dashboard’s Schema tab to see the derived names for your tables.

`tables[].reverse_relations`

Controls which reverse relations (foreign keys on other tables pointing back to this one) are exposed.

reverse_relations:
  exclude: [comments, likes]

Only exclude is supported for reverse relations. If omitted, all reverse relations are included.

Where

Row predicates are SQL WHERE conditions baked into the snapshot at load time. They filter which rows are included — reducing memory usage and hiding rows that should never be queryable (e.g. soft-deleted records).

Global predicate

where: "deleted_at IS NULL"

Applied to every table in the schema. Use where_columns to guard against tables that don’t have the column:

where: "deleted_at IS NULL"
where_columns:
  - deleted_at       # only apply to tables that have this column

Tables missing any column listed in where_columns skip the predicate entirely.

Per-table predicate

tables:
  - name: users
    where: "active = 1"      # overrides global predicate for this table
  - name: archived_orders
    where: ""                # empty string = opt out of global predicate

A non-empty where on a table overrides the global predicate. An empty string explicitly disables it for that table.

Example

version: 1

# Exclude soft-deleted rows globally, but only for tables that have the column
where: "deleted_at IS NULL"
where_columns: [deleted_at]

tables:
  - name: users
    columns: [id, name, email, plan, created_at, deleted_at]

  - name: sessions
    columns: [id, user_id, token, created_at]
    where: "expires_at > NOW()"   # sessions use a different predicate

  - name: audit_logs
    columns: [id, user_id, action, created_at]
    where: ""                      # include all rows regardless of global predicate

Aliases

Field aliases let you rename tables and fields in the generated API without changing your MySQL schema.

Table alias

tables:
  - name: users
    alias: members     # API exposes this as "members", not "users"

Field aliases

field_aliases maps from the derived API name to the alias you want exposed. For scalar columns the derived name is the column name; for relations it’s the derived relation name (FK column with _id stripped).

tables:
  - name: posts
    field_aliases:
      title: headline          # scalar column rename
      author: writer           # FK relation rename (author_id → author → writer)
      comments: replies        # reverse relation rename

Field notes

field_notes adds descriptions to fields in the generated OpenAPI spec. Keys follow the same naming convention as field_aliases.

tables:
  - name: users
    field_notes:
      id: "Primary key"
      plan: "Subscription tier: free, pro, teams, business, or enterprise"

Full example

version: 1
tables:
  - name: users
    alias: members
    columns: [id, name, email, plan, created_at]
    field_aliases:
      name: display_name
      posts: articles
    field_notes:
      id: "Unique user identifier"
      plan: "Current subscription plan"

  - name: posts
    columns: [id, user_id, title, slug, body, published_at]
    relations:
      include: [author]
    field_aliases:
      author: writer
      title: headline

Example

version: 1
tables:
  - name: users
    columns: [id, name, email, plan, created_at]
    reverse_relations:
      exclude: [audit_logs]   # too noisy to include

  - name: posts
    columns: [id, user_id, title, slug, body, published_at]
    relations:
      include: [author]       # only expose the author relation
    reverse_relations:
      exclude: [post_views]

  - name: comments
    columns: [id, post_id, user_id, body, created_at]
    relations:
      include: [author, post]

Applying changes

After uploading a new config:

If the instance is not yet provisioned: the config will be compiled in on next provision.
If the instance is running: click Rebuild to trigger a new build with the updated config. The instance stays running until the rebuild completes and is hot-swapped.