# What is TeslaMate.Repo? The Central Database Gateway Explained

> Discover TeslaMate Repo, the Ecto repository acting as your central database gateway for all PostgreSQL operations in TeslaMate. Learn how it simplifies data access.

- Repository: [TeslaMate/teslamate](https://github.com/teslamate-org/teslamate)
- Tags: deep-dive
- Published: 2026-06-18

---

**TeslaMate.Repo is the Ecto repository module that serves as the single entry point for all PostgreSQL database operations in the TeslaMate project**, abstracting raw SQL behind a clean Elixir API while ensuring transactional safety and test isolation.

TeslaMate.Repo acts as the persistence layer for the TeslaMate self-hosted data logger, handling every read and write operation across vehicle telemetry, charging sessions, and geofence data. Defined in [`lib/teslamate/repo.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/repo.ex), this module configures the PostgreSQL adapter and provides the foundation for the application's data integrity.

## Defining TeslaMate.Repo in lib/teslamate/repo.ex

The repository is declared once in the codebase using `Ecto.Repo` with the PostgreSQL adapter specified. This configuration establishes the connection pool and OTP application context required for all database interactions.

```elixir
defmodule TeslaMate.Repo do
  use Ecto.Repo,
    otp_app: :teslamate,
    adapter: Ecto.Adapters.Postgres
end

```

*File:* [`lib/teslamate/repo.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/repo.ex) — Contains the module definition specifying `:teslamate` as the OTP application and `Ecto.Adapters.Postgres` as the storage backend.

## Database Operations and CRUD Patterns

Throughout the TeslaMate codebase, `TeslaMate.Repo` is aliased and invoked as the central access point for persistent data. Rather than modules executing raw SQL, they delegate to the repository functions, ensuring consistent query semantics and connection handling.

### Settings Management

The settings module relies on the repo to load and update both global configuration and per-car preferences. In [`lib/teslamate/settings.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/settings.ex), database calls retrieve current values and persist changes atomically.

### Vehicle Data Handling

Vehicle creation, updates, and association preloading occur through the repo in [`lib/teslamate/vehicles/vehicle.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/vehicles/vehicle.ex). When the application registers a new Tesla vehicle or updates its display name, it delegates the storage operation to `TeslaMate.Repo`.

### Logging and Location Tracking

Drive logs, charge sessions, position data, and state changes are persisted via the repo in [`lib/teslamate/log.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/log.ex). Similarly, address resolution and geofence definitions in [`lib/teslamate/locations.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/locations.ex) use the repository to store location metadata and execute spatial queries.

## Transactional Safety with Repo.transaction

Many modules wrap related database calls in `Repo.transaction/1` to guarantee atomicity. This pattern prevents partial writes during complex operations such as vehicle creation or batch repairs, maintaining data consistency across related tables.

For example, when changing a vehicle's properties, the code executes within a transaction block:

```elixir
Repo.transaction(fn ->
  car
  |> Car.changeset(%{name: "New name"})
  |> Repo.update()
end)

```

*File:* [`lib/teslamate/vehicles/vehicle.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/vehicles/vehicle.ex) — Demonstrates atomic updates using transactional boundaries.

## Test Isolation via Ecto Sandbox

In the test suite, `TeslaMate.Repo` connects to `Ecto.Adapters.SQL.Sandbox` rather than the production database. This adapter allows tests to run in parallel with isolated database states, rolling back changes after each test case to ensure reproducibility.

The setup occurs in the test support files:

```elixir
{:ok, _pid} = Ecto.Adapters.SQL.Sandbox.start_owner!(TeslaMate.Repo, shared: true)

```

*File:* [`test/support/data_case.ex`](https://github.com/teslamate-org/teslamate/blob/main/test/support/data_case.ex) (lines 19-29) — Initializes the sandbox owner for isolated test execution.

## Code Examples in Action

### Starting the Repository

Under the OTP application supervision tree, the repo initializes alongside other workers:

```elixir
def start(_type, _args) do
  children = [
    TeslaMate.Repo,
    # … other workers …

  ]

  Supervisor.start_link(children, strategy: :one_for_one)
end

```

*File:* [`lib/teslamate/application.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/application.ex) — Adds the repository to the supervision tree at application startup.

### Fetching Records

Simple queries retrieve all records for a given schema:

```elixir
def list_cars do
  Repo.all(TeslaMate.Log.Car)
end

```

*File:* [`lib/teslamate/log.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/log.ex) — Uses `Repo.all/1` to fetch vehicle entries.

### Transactional Updates

Complex updates ensure data integrity through transaction blocks:

```elixir
Repo.transaction(fn ->
  car
  |> Car.changeset(%{name: "New name"})
  |> Repo.update()
end)

```

*File:* [`lib/teslamate/vehicles/vehicle.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/vehicles/vehicle.ex) — Wraps the changeset operation in a transaction.

### Test Database Setup

Tests acquire a database connection through the sandbox:

```elixir
{:ok, _pid} = Ecto.Adapters.SQL.Sandbox.start_owner!(TeslaMate.Repo, shared: true)

```

*File:* [`test/support/data_case.ex`](https://github.com/teslamate-org/teslamate/blob/main/test/support/data_case.ex) — Configures the repository for isolated test contexts.

## Summary

- **TeslaMate.Repo** is defined in [`lib/teslamate/repo.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/repo.ex) using `Ecto.Repo` with the PostgreSQL adapter.
- It serves as the **single source of truth** for all persistence, handling settings, vehicle data, logs, and locations.
- **Transactional safety** is enforced via `Repo.transaction/1` to prevent partial writes during complex operations.
- The test suite leverages **Ecto.Adapters.SQL.Sandbox** through `TeslaMate.Repo` to ensure isolated, parallel test execution.

## Frequently Asked Questions

### What database does TeslaMate.Repo use?

**TeslaMate.Repo uses PostgreSQL** via `Ecto.Adapters.Postgres`, as configured in the module definition in [`lib/teslamate/repo.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/repo.ex). All persistent data—including vehicle telemetry, settings, and geofences—is stored in a PostgreSQL database instance.

### How does TeslaMate.Repo ensure data consistency during updates?

**The repository ensures consistency through Ecto transactions.** Modules such as [`lib/teslamate/vehicles/vehicle.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/vehicles/vehicle.ex) wrap related database operations in `Repo.transaction/1`, which guarantees that either all changes persist successfully or none do, preventing partial writes.

### Is TeslaMate.Repo used in the test environment?

**Yes, but with a different adapter.** In tests, `TeslaMate.Repo` runs under `Ecto.Adapters.SQL.Sandbox` (configured in [`test/support/data_case.ex`](https://github.com/teslamate-org/teslamate/blob/main/test/support/data_case.ex)), which provides isolated database connections per test. This allows tests to run in parallel without interfering with each other's data.

### Where is TeslaMate.Repo initialized in the application?

**The repository starts within the OTP supervision tree** defined in [`lib/teslamate/application.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/application.ex). It is listed as a child process supervised by the main application supervisor, ensuring it restarts automatically if the database connection fails.