Tutorial: Your First Repository

In this tutorial, you’ll:

• Create a Horizon Epoch repository
• Register a PostgreSQL table
• Make your first commit
• Explore the history

Prerequisites

• Horizon Epoch installed (Installation Guide)
• PostgreSQL running with a sample database

Step 1: Create Sample Data

First, let’s create a sample table in PostgreSQL:

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

INSERT INTO users (name, email) VALUES
    ('Alice', 'alice@example.com'),
    ('Bob', 'bob@example.com'),
    ('Charlie', 'charlie@example.com');

Step 2: Initialize Repository

epoch init my-first-repo \
  --metadata-url "postgresql://localhost/horizon_epoch" \
  --description "My first Horizon Epoch repository"

Output:

Initialized repository 'my-first-repo' on branch 'main'

Step 3: Register the Table

epoch table add users \
  --location "postgresql://localhost/mydb/public.users"

Output:

Registered table 'users' with 3 records
  Schema: id (int), name (text), email (text), created_at (timestamp)
  Primary key: id

Step 4: Create Initial Commit

epoch commit -m "Initial import of users table"

Output:

Created commit abc123f
  1 table, 3 records

Step 5: View the Log

epoch log

Output:

commit abc123f
Author: Your Name <you@example.com>
Date:   Thu Dec 12 10:30:00 2025

    Initial import of users table

    Tables: users
    Stats: 3 records added

Step 6: Check Status

epoch status

Output:

On branch main
nothing to commit, working tree clean

Congratulations!

You’ve created your first Horizon Epoch repository. Next steps:

• Branching Workflow - Learn about branches
• Merging Data - Combine changes