Skip to content

✨ Database Migration

These notes only apply to TruLens developments that change the database schema.

Creating a new schema revision

If upgrading DB, You must do this step!!

  1. Make desired changes to SQLAlchemy orm models in src/core/trulens/core/database/orm.py.
  2. Run automatic alembic revision script generator. This will generate a new Python script in src/core/trulens/core/database/migrations.
  3. cd src/core/trulens/core/database/migrations
  4. SQLALCHEMY_URL="sqlite:///../../../../../../default.sqlite" alembic revision --autogenerate -m "<short_description>" --rev-id "<next_integer_version>"
  5. Check over the automatically generated script in src/core/trulens/core/database/migration/versions to make sure it looks correct.
  6. Get a database with the new changes:
  7. rm default.sqlite
  8. Run TruSession() to create a fresh database that uses the new ORM.
  9. Add the version to src/core/trulens/core/database/migrations/data.py in the variable sql_alchemy_migration_versions
  10. Make any sqlalchemy_upgrade_paths updates in src/core/trulens/core/database/migrations/data.py if a backfill is necessary.

Creating a DB at the latest schema

If upgrading DB, You must do this step!!

Note: You must create a new schema revision before doing this

Note: Some of these instructions may be outdated and are in progress if being updated.

  1. Create a sacrificial OpenAI Key (this will be added to the DB and put into github; which will invalidate it upon commit)
  2. cd tests/docs_notebooks/notebooks_to_test
  3. remove any local dbs
  4. rm -rf default.sqlite
  5. run below notebooks (Making sure you also run with the most recent code in trulens) TODO: Move these to a script
  6. all_tools.ipynb # cp ../../../generated_files/all_tools.ipynb ./
  7. llama_index_quickstart.ipynb # cp ../../../examples/quickstart/llama_index_quickstart.ipynb ./
  8. langchain-retrieval-augmentation-with-trulens.ipynb # cp ../../../examples/vector-dbs/pinecone/langchain-retrieval-augmentation-with-trulens.ipynb ./
  9. Add any other notebooks you think may have possible breaking changes
  10. replace the last compatible db with this new db file
  11. Use the version you chose for --rev-id
  12. mkdir release_dbs/sql_alchemy_<NEW_VERSION>/
  13. cp default.sqlite release_dbs/sql_alchemy_<NEW_VERSION>/
  14. git add release_dbs

Testing the DB

Run the tests with the requisite env vars.

HUGGINGFACE_API_KEY="<to_fill_out>" \
OPENAI_API_KEY="<to_fill_out>" \
PINECONE_API_KEY="<to_fill_out>" \
PINECONE_ENV="<to_fill_out>" \
HUGGINGFACEHUB_API_TOKEN="<to_fill_out>" \
python -m pytest tests/docs_notebooks -k backwards_compat