Index Refactoring

Since v17, the backend items index (Cadmus.Index*) was rewritten in plain SQL for PostgreSQL, dropping Entity Framework and the unused SqlKata dependency, fixing several bugs, and optimizing its schema.

Update

Solutions depending on these packages (API and CLI projects) should:

  1. update all the Cadmus packages to 17.0.0, and remove any reference to Cadmus.Index.Ef or Cadmus.Index.Sql, which no longer exist. Replace Cadmus.Index.Ef.PgSql with Cadmus.Index.PgSql where possible; keeping it still works, as a deprecated shim.

  2. index factory providers: projects with their own provider (e.g. StandardItemIndexFactoryProvider in CLI tools) should register both assemblies, so that both the new and the legacy tags are resolved:

    ItemIndexFactory.ConfigureServices(services,
    // Cadmus.Index.PgSql
    typeof(PgSqlItemIndexWriter).Assembly,
    // Cadmus.Index.Ef.PgSql (legacy tags)
#pragma warning disable CS0618
    typeof(Cadmus.Index.Ef.PgSql.EfPgSqlItemIndexWriter).Assembly);
#pragma warning restore CS0618

    Providers registering only the legacy assembly keep working with profiles using the legacy tags. API projects using Cadmus.Api.Services need no change.

  3. profiles (optional, recommended): replace item-index-writer.ef-pg with item-index-writer.pgsql, and item-index-reader.ef-pg with item-index-reader.pgsql. This requires a provider registering Cadmus.Index.PgSql (see above).
  4. code using the index directly (obsolete members produce warnings, but keep working as before):
    • await writer.WriteItemAsync(item) instead of writer.WriteItem(item), and so on for the other members; remove Close() calls. Note that calls to the obsolete members are now blocking until completion, so that non-awaited calls (e.g. _indexWriter.WriteItem(item); in importers) still work.
    • await indexer.BuildAsync(repository, filter, progress, cancel) instead of indexer.Build(repository, filter, cancel, progress) (mind the parameters order); ClearAsync instead of Clear.
    • PgSqlIndexSchema.GetSql() instead of EfPgSqlItemIndexWriter.GetPgSqlSchema().
    • PgSqlQueryBuilder.BuildItemQuery/BuildPinQuery instead of BuildForItem/BuildForPin.
  5. databases: no action required. Existing index databases are upgraded in place at the first API startup: for big indexes this rewrites the item and pin tables once, which may take some time (the startup waits for it). Alternatively, run cadmus-tool create-db index <name> before deploying, or drop the index database and rebuild it with cadmus-tool index.