For the complete documentation index, see llms.txt. This page is also available as Markdown.

SQL database (Postgres, MySQL)

Create a database user so Terra can write events to your Postgres or MySQL database, and read the tables it creates.

SQL databases are easy to set up and often the go-to choices for less abstracted storage solutions. Terra supports Postgres and MySQL. This page covers creating a database user for Terra, adding the destination, and the tables Terra writes.

Before you begin

  • A Postgres or MySQL database reachable from Terra's servers.

Create a database user

Create a user with enough permissions to create tables and have read & write access within those tables. You can execute the scripts below based on your database:

Terra creates tables under a dedicated terra schema. Your database user needs the following permissions:

CREATE USER terra_user WITH PASSWORD 'your_password';
GRANT CONNECT ON DATABASE your_database_name TO terra_user;
CREATE SCHEMA IF NOT EXISTS terra;
GRANT USAGE ON SCHEMA terra TO terra_user;
GRANT CREATE ON SCHEMA terra TO terra_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA terra
GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO terra_user;
CREATE USER 'terra_user'@'%' IDENTIFIED BY 'your_password';
GRANT CREATE, SELECT, INSERT, UPDATE, DELETE ON your_database_name.* TO 'terra_user'@'%';

Add the destination in Terra

On the Connections page in your Terra dashboard, click Add New and add the SQL destination. Enter your database host, port, database name, username, and password, then click Apply.

What Terra writes

Terra creates three tables in your database:

All tables are created under the terra schema (e.g. terra.terra_users).

Tables are created in the database you specify (no schema prefix).

How Terra uses each table:

  • terra_users: a row is created (or updated) for each user on auth_success events.

  • terra_data_payloads: each data event (activity, sleep, body, etc.) gets a row. The actual data payload is stored in a Terra-managed bucket, and the payload_url column contains a pre-signed download link.

  • terra_other_payloads: all non-data events (deauth, access revoked, etc.) get a row, with the full event payload available via payload_url.

Next steps

Last updated

Was this helpful?