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

VoiceStudio stores all persistent data in a local SQLite database defined by DB_PATH in 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. 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 (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.

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.

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.

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, 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 that initializes the database (including running pending migrations) and returns a preconfigured SQLAlchemy Engine.

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 — Defines DB_PATH and all data-directory constants.
• backend/migrations/env.py — Configures the SQLAlchemy URL for Alembic using DB_PATH.
• backend/core/db.py — Provides get_engine() and migration helpers.
• backend/api/routers/settings.py — Demonstrates practical read/write patterns against the database.
• 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.
• 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, 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, 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 (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 file demonstrates backup-related logic that references this file path.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}