Database schema & Alembic

Create Lokit's PostgreSQL schema directly or incorporate its ordered, versioned SQL into your application's Alembic history.

Two supported schema ownership models

Call TranslationMemory.setup() when Lokit owns initialization for a dedicated translation-memory database. Use database_schema_statements() when the containing application owns DDL through Alembic or another migration system. Both paths create the same current schema and record the same DATABASE_SCHEMA_VERSION; do not mix ownership casually after deployment.

Use the ordered statement API

database_schema_statements(partitioned=True, include_extensions=True) returns an ordered tuple[str, ...]. Every item is one individually executable, semicolon-terminated statement. This is the stable migration-tool boundary—Lokit intentionally does not require an application's SQLAlchemy declarative base or migration graph.

inspect_schema.py

from lokit.database import (    DATABASE_SCHEMA_VERSION,    database_schema_statements,)
statements: tuple[str, ...] = database_schema_statements(    partitioned=True,    include_extensions=True,)
print(DATABASE_SCHEMA_VERSION)for statement in statements:    print(statement)

Apply it from an Alembic revision

Execute the statements in the order returned. The helper creates extensions first, then _lokit_meta, the selected table layout, shared indexes and child tables, and finally schema metadata. Downgrade policy remains application-owned because dropping a translation memory is destructive and environment-specific.

versions/add_lokit_tm.py

from alembic import opfrom lokit.database import database_schema_statements

def upgrade() -> None:    for statement in database_schema_statements(        partitioned=True,        include_extensions=False,    ):        op.execute(statement)

def downgrade() -> None:    raise NotImplementedError(        "Define an application-specific data retention policy"    )

Understand the physical schema

Object	Purpose
`_lokit_meta`	Records schema version, creation time, and partitioning choice
`translation_units`	Sources, targets, locales, context, status, plurals, project/domain, hashes, and JSON extensions
`unit_tags`	Source and target inline-tag identity and attributes
`segment_parts`	Ordered text and code parts used to reconstruct inline content
`unit_comments`	Comment context, origin, timestamps, and extensions
GIN trigram index	Supplies similarity candidates for source-text matching
Hash and locale indexes	Accelerate exact, contextual, locale, project, and domain lookups

Partitioning is an initial design choice

The default schema partitions translation_units by source_locale and creates locale partitions lazily during ingestion. Pass partitioned=False for one flat table. Lokit records the choice in _lokit_meta; setup() raises if a later call requests a different layout instead of attempting an unsafe online conversion.

Manage extension privileges explicitly

The full statement set includes CREATE EXTENSION IF NOT EXISTS pg_trgm and pgcrypto. If database administrators manage extensions separately, call database_schema_statements(include_extensions=False) and provision both extensions before using the schema. pg_trgm supports similarity candidates and pgcrypto supplies gen_random_uuid().

Version checks protect newer schemas

DATABASE_SCHEMA_VERSION currently represents the schema emitted by the installed Lokit version. setup() refuses to open a schema whose recorded version is newer than the library, preventing an older application from writing through an unknown layout. Keep the Lokit package version and application migration that introduced its schema statements together in deployment history.