# How to Connect to the VoiceStudio Backend Database: 3 Methods Explained

> Learn how to connect to the VoiceStudio backend database. Explore three methods: sqlite3, SQLAlchemy, and the internal get_engine() helper for seamless data access.

- Repository: [Palash Debnath/VoiceStudio](https://github.com/debpalash/VoiceStudio)
- Tags: how-to-guide
- Published: 2026-09-11

---

**VoiceStudio stores all persistent data in a local SQLite database defined by `DB_PATH` in [`backend/core/config.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/config.py), and you can connect to it using Python's built-in `sqlite3` module, SQLAlchemy, or the internal `get_engine()` helper.**

The open-source **debpalash/VoiceStudio** project uses a file-based SQLite database named `omnivoice.db` to manage projects, voice profiles, settings, and logs. Whether you are debugging data issues, running ad-hoc analytics, or building external integrations, connecting to this backend database requires knowing the correct file path and choosing the right connection method for your use case.

## Database Location and Configuration

VoiceStudio determines the database location at runtime in [`backend/core/config.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/config.py). The constant **`DB_PATH`** is constructed by joining the application data directory (`DATA_DIR`) with the filename `omnivoice.db` (lines 71-73).

When the FastAPI backend boots, it reads this path to configure the SQLAlchemy engine used for ORM operations and Alembic migrations in [`backend/migrations/env.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/migrations/env.py) (lines 44-52). Always reference `DB_PATH` dynamically rather than hardcoding paths to ensure you target the active database file.

## Method 1: Direct SQLite Connection (Python sqlite3)

For quick debugging or simple read-only queries, use the standard library `sqlite3` module. This approach imports `DB_PATH` directly from the configuration to guarantee you connect to the same file the application uses.

```python
from backend.core.config import DB_PATH
import sqlite3

# Open a connection (read-only or read-write as needed)

with sqlite3.connect(DB_PATH) as conn:
    cursor = conn.cursor()
    
    # List all tables in the schema

    cursor.execute("SELECT name FROM sqlite_master WHERE type='table'")
    tables = [row[0] for row in cursor.fetchall()]
    print("Tables:", tables)
    
    # Fetch recent projects

    cursor.execute(
        "SELECT id, name, created_at FROM projects ORDER BY created_at DESC LIMIT 5"
    )
    recent = cursor.fetchall()
    for proj in recent:
        print(proj)

```

This pattern mirrors the database interactions found in the test suite, such as in [`tests/test_worker_upload_server.py`](https://github.com/debpalash/VoiceStudio/blob/main/tests/test_worker_upload_server.py).

## Method 2: SQLAlchemy Engine (Production-Grade)

For applications requiring connection pooling, transaction management, or ORM compatibility, instantiate a SQLAlchemy engine using the same URL configuration that VoiceStudio uses for migrations.

```python
from backend.core.config import DB_PATH
from sqlalchemy import create_engine, text

# Construct the SQLite URL

engine = create_engine(f"sqlite:///{DB_PATH}")

# Example: Count voice profiles

with engine.connect() as conn:
    result = conn.execute(text("SELECT COUNT(*) FROM voices"))
    count = result.scalar_one()
    print(f"Number of voice profiles: {count}")

# Example: Insert a new setting transactionally

with engine.begin() as conn:
    conn.execute(
        text("INSERT INTO settings (key, value) VALUES (:k, :v)"),
        {"k": "example_flag", "v": "true"},
    )

```

As implemented in [`backend/migrations/env.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/migrations/env.py), this engine powers all Alembic migrations and is the canonical way to interact with the database at the SQL level.

## Method 3: Using the Internal Database Helper

VoiceStudio ships with a convenience wrapper in [`backend/core/db.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/db.py) that initializes the database (including running pending migrations) and returns a preconfigured SQLAlchemy `Engine`.

```python
from backend.core.db import get_engine

# Returns an initialized engine using DB_PATH internally

engine = get_engine()

# Execute queries

with engine.connect() as conn:
    rows = conn.execute(text("SELECT * FROM settings")).fetchall()
    print(rows)

```

Using `get_engine()` ensures your connection respects the application's startup logic, including any migration checks or initialization routines defined in the core database module.

## Key Files Reference

- **[`backend/core/config.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/config.py)** — Defines `DB_PATH` and all data-directory constants.
- **[`backend/migrations/env.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/migrations/env.py)** — Configures the SQLAlchemy URL for Alembic using `DB_PATH`.
- **[`backend/core/db.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/db.py)** — Provides `get_engine()` and migration helpers.
- **[`backend/api/routers/settings.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/settings.py)** — Demonstrates practical read/write patterns against the database.
- **[`tests/test_worker_upload_server.py`](https://github.com/debpalash/VoiceStudio/blob/main/tests/test_worker_upload_server.py)** — Shows typical `sqlite3.connect(DB_PATH)` usage in integration tests.

## Summary

- **VoiceStudio uses SQLite**: All data persists to a local `omnivoice.db` file defined by `DB_PATH` in [`backend/core/config.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/config.py).
- **Three connection methods**: Use `sqlite3` for quick scripts, SQLAlchemy for production tools, or `get_engine()` for application-consistent access.
- **Always import the path**: Reference `backend.core.config.DB_PATH` rather than hardcoding file locations to ensure compatibility with the running instance.
- **Migration awareness**: When using [`backend/core/db.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/db.py), pending migrations execute automatically before the engine is returned.

## Frequently Asked Questions

### What type of database does VoiceStudio use?

VoiceStudio uses a local **SQLite** database. According to the source code in [`backend/core/config.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/config.py), the application stores all persistent data in a single file named `omnivoice.db`, which is accessed via the `DB_PATH` configuration constant.

### Where is the VoiceStudio database file located?

The database file location is dynamic and resolved at runtime in [`backend/core/config.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/config.py) (lines 71-73). It resides in the application data directory (`DATA_DIR`) under the filename `omnivoice.db`. Import `DB_PATH` from the configuration module to get the absolute path programmatically.

### Can I connect to the database while VoiceStudio is running?

Yes, SQLite supports concurrent read access from multiple processes. However, write operations will lock the database file. For read-only analytics or debugging, use `sqlite3.connect(DB_PATH)` or SQLAlchemy with the `sqlite:///` URL. Avoid long-running write transactions that could block the main VoiceStudio backend.

### How do I backup the VoiceStudio database?

Since VoiceStudio uses a standard SQLite file, backup is as simple as copying the `omnivoice.db` file located at `DB_PATH`. Ensure the application is not writing to the database during the copy to prevent corruption. The [`backend/api/routers/settings.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/settings.py) file demonstrates backup-related logic that references this file path.