Zephyr.toml: Define the Tables Structure

The zephyr.toml is a crucial part of the newer versions of the Zephyr client-side tooling. The file is used to define the zephyr-related configurations of your rust crate. More specifically it defines the tables that your ingestion program will read from or write to during the execution. Besides the tables, you'll also have to define the columns for each of the tables you declare.

Choosing a Table's Structure

How can we define Zephyr tables then? Zephyr tables are effectively translated to PostgreSQL tables under the hood (that is, on the host server). In light of this, we recommend following a layout that is SQL-efficient.

Let's follow a simple example of how a zephyr.toml file with multiple tables would look:

zephyr.toml

name = "feedback-indexer"


// first table
[[tables]]
name = "feedback"

[[tables.columns]]
name = "source"
col_type = "BYTEA"

[[tables.columns]]
name = "hash"
col_type = "BYTEA"

[[tables.columns]]
name = "text"
col_type = "BYTEA"

[[tables.columns]]
name = "votes"
col_type = "BYTEA"


// second table
[[tables]]
name = "score"

[[tables.columns]]
name = "source"
col_type = "BYTEA"

[[tables.columns]]
name = "upvote"
col_type = "BYTEA"

At the top of the file we always define the name of the program (this example is taken from the onchain-stellar-complaints indexer example). Next, we have two tables. First, we define for each table the table name, and then we specify the columns one by one.

Table Naming

For what concerns naming, we are currently leveraging the ease of packing string-alike objects into integers through Sorban symbols, i.e. we are using symbols for table and column names. This means that table/column names can only be up to 9 characters, and that supported characters are a-zA-Z0-9_.

This means that table names will likely have to be abbreviated: "current_sequence" won't work while "curr_seq" will.