@takaro/db 0.0.0-next.0da151e

package/src/migrations/sql/20250719160409-add-module-author-supportedgames.ts

@@ -0,0 +1,31 @@
+import { Knex } from 'knex';
+
+/**
+ * This migration adds author and supportedGames fields to the modules table
+ * @param knex
+ */
+
+export async function up(knex: Knex): Promise<void> {
+  // Add author column
+  await knex.schema.alterTable('modules', (table) => {
+    table.string('author').nullable();
+  });
+
+  // Add supportedGames column as JSON array
+  await knex.schema.alterTable('modules', (table) => {
+    table.json('supportedGames').defaultTo('["all"]');
+  });
+
+  // Update existing modules to have default values
+  await knex('modules').update({
+    author: 'Unknown',
+    supportedGames: JSON.stringify(['all']),
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.alterTable('modules', (table) => {
+    table.dropColumn('author');
+    table.dropColumn('supportedGames');
+  });
+}

package/src/migrations/sql/20250719175542-add-discord-permissions.ts

@@ -0,0 +1,20 @@
+import { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  await knex('permission').insert([
+    {
+      permission: 'VIEW_DISCORD_INFO',
+      description: 'Can view Discord guild information including channels and roles',
+      friendlyName: 'View Discord Info',
+    },
+    {
+      permission: 'SEND_DISCORD_MESSAGE',
+      description: 'Can send messages to Discord channels',
+      friendlyName: 'Send Discord Messages',
+    },
+  ]);
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex('permission').whereIn('permission', ['VIEW_DISCORD_INFO', 'SEND_DISCORD_MESSAGE']).del();
+}

package/src/migrations/sql/20250726000000-discord-role-sync.ts

@@ -0,0 +1,15 @@
+import { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  // Add linkedDiscordRoleId to roles table
+  await knex.schema.alterTable('roles', (table) => {
+    table.string('linkedDiscordRoleId').nullable();
+    table.index('linkedDiscordRoleId');
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.alterTable('roles', (table) => {
+    table.dropColumn('linkedDiscordRoleId');
+  });
+}

package/src/migrations/sql/20250727092719-add-quality-to-inventory.ts

@@ -0,0 +1,13 @@
+import { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.alterTable('playerInventoryHistory', (table) => {
+    table.string('quality').nullable();
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.alterTable('playerInventoryHistory', (table) => {
+    table.dropColumn('quality');
+  });
+}

package/src/migrations/sql/20250802124307-add-playeriphistory-composite-index.ts

@@ -0,0 +1,13 @@
+import { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.alterTable('playerIpHistory', (table) => {
+    table.index(['domain', 'playerId', 'createdAt'], 'idx_playeriphistory_domain_playerid_createdat');
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.alterTable('playerIpHistory', (table) => {
+    table.dropIndex([], 'idx_playeriphistory_domain_playerid_createdat');
+  });
+}

package/src/migrations/sql/20250809122020-add-player-name-history.ts

@@ -0,0 +1,31 @@
+import { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.createTable('playerNameHistory', (table) => {
+    table.uuid('id').primary().defaultTo(knex.raw('gen_random_uuid ()'));
+    table.timestamps(true, true, true);
+    table.string('domain').references('domains.id').onDelete('CASCADE').notNullable();
+    table.uuid('playerId').references('players.id').onDelete('CASCADE').notNullable();
+    table.uuid('gameServerId').references('gameservers.id').onDelete('SET NULL').nullable();
+    table.string('name').notNullable();
+
+    // Indexes for performance
+    table.index(['playerId', 'createdAt'], 'idx_player_name_history_player_created');
+    table.index('name', 'idx_player_name_history_name');
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  // Update players table with latest name from history before dropping
+  const latestNames = await knex('playerNameHistory')
+    .select('playerId', 'name')
+    .distinctOn('playerId')
+    .orderBy('playerId')
+    .orderBy('createdAt', 'desc');
+
+  for (const record of latestNames) {
+    await knex('players').where('id', record.playerId).update({ name: record.name });
+  }
+
+  await knex.schema.dropTable('playerNameHistory');
+}

package/src/migrations/sql/20250812163648-add-kpi-performance-indexes.ts

@@ -0,0 +1,20 @@
+import { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  // Add index for playerOnGameServer activity queries (DAU/WAU/MAU)
+  await knex.schema.raw(`
+    CREATE INDEX IF NOT EXISTS idx_pog_domain_lastseen 
+    ON "playerOnGameServer"(domain, "lastSeen" DESC)
+  `);
+
+  // Add index for user activity queries
+  await knex.schema.raw(`
+    CREATE INDEX IF NOT EXISTS idx_users_domain_lastseen
+    ON users(domain, "lastSeen" DESC)
+  `);
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.raw('DROP INDEX IF EXISTS idx_pog_domain_lastseen');
+  await knex.schema.raw('DROP INDEX IF EXISTS idx_users_domain_lastseen');
+}

package/src/migrations/sql/20250814163747-shop-order-cascade-delete.ts

@@ -0,0 +1,27 @@
+import { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.raw(`
+    ALTER TABLE "shopOrder" 
+    DROP CONSTRAINT IF EXISTS shoporder_playerid_foreign;
+  `);
+
+  await knex.raw(`
+    ALTER TABLE "shopOrder" 
+    ADD CONSTRAINT shoporder_playerid_foreign 
+    FOREIGN KEY ("playerId") REFERENCES players(id) ON DELETE CASCADE;
+  `);
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.raw(`
+    ALTER TABLE "shopOrder" 
+    DROP CONSTRAINT IF EXISTS shoporder_playerid_foreign;
+  `);
+
+  await knex.raw(`
+    ALTER TABLE "shopOrder" 
+    ADD CONSTRAINT shoporder_playerid_foreign 
+    FOREIGN KEY ("playerId") REFERENCES players(id) ON DELETE NO ACTION;
+  `);
+}

package/src/migrations/sql/20250815120000-optimize-shop-analytics-indexes.ts

@@ -0,0 +1,46 @@
+import { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  // Index for filtering orders by domain, status, and date range
+  await knex.raw(`
+    CREATE INDEX IF NOT EXISTS idx_shoporder_analytics 
+    ON "shopOrder" (domain, status, "createdAt")
+    WHERE status IN ('COMPLETED', 'PAID')
+  `);
+
+  // Index for joining orders with listings and filtering by date
+  await knex.raw(`
+    CREATE INDEX IF NOT EXISTS idx_shoporder_listing_date 
+    ON "shopOrder" ("listingId", "createdAt")
+    WHERE status IN ('COMPLETED', 'PAID')
+  `);
+
+  // Index for customer analytics (unique players)
+  await knex.raw(`
+    CREATE INDEX IF NOT EXISTS idx_shoporder_player_analytics 
+    ON "shopOrder" (domain, "playerId", "createdAt")
+    WHERE status IN ('COMPLETED', 'PAID')
+  `);
+
+  // Composite index for shop listings to speed up joins
+  await knex.raw(`
+    CREATE INDEX IF NOT EXISTS idx_shoplisting_composite 
+    ON "shopListing" (id, "gameServerId", price)
+    WHERE "deletedAt" IS NULL AND draft = false
+  `);
+
+  // Index for filtering listings by game server and active status
+  await knex.raw(`
+    CREATE INDEX IF NOT EXISTS idx_shoplisting_active 
+    ON "shopListing" (domain, "gameServerId")
+    WHERE "deletedAt" IS NULL AND draft = false
+  `);
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.raw('DROP INDEX IF EXISTS idx_shoporder_analytics');
+  await knex.raw('DROP INDEX IF EXISTS idx_shoporder_listing_date');
+  await knex.raw('DROP INDEX IF EXISTS idx_shoporder_player_analytics');
+  await knex.raw('DROP INDEX IF EXISTS idx_shoplisting_composite');
+  await knex.raw('DROP INDEX IF EXISTS idx_shoplisting_active');
+}

package/src/migrations/sql/20251014120000-shop-order-auto-cancel-on-listing-delete.ts

@@ -0,0 +1,75 @@
+import { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  // Step 1: Create trigger function that auto-cancels orders when listing is deleted
+  await knex.raw(`
+    CREATE OR REPLACE FUNCTION cancel_orders_on_listing_delete()
+    RETURNS TRIGGER AS $$
+    BEGIN
+      -- Only proceed if deletedAt changed from NULL to a value (soft-delete)
+      IF OLD."deletedAt" IS NULL AND NEW."deletedAt" IS NOT NULL THEN
+        -- Cancel all PAID orders for this listing and refund currency
+        -- Aggregate refunds by player to handle multiple orders correctly
+        WITH orders_to_cancel AS (
+          SELECT
+            so.id AS order_id,
+            so."playerId",
+            NEW."gameServerId",
+            NEW.domain AS domain,
+            NEW.price * so.amount AS refund_amount
+          FROM "shopOrder" so
+          WHERE so."listingId" = NEW.id
+            AND so.status = 'PAID'
+        ),
+        aggregated_refunds AS (
+          SELECT
+            "playerId",
+            "gameServerId",
+            domain,
+            SUM(refund_amount) AS total_refund
+          FROM orders_to_cancel
+          GROUP BY "playerId", "gameServerId", domain
+        )
+        -- Update playerOnGameServer currency with aggregated total
+        UPDATE "playerOnGameServer" pogs
+        SET currency = pogs.currency + ar.total_refund
+        FROM aggregated_refunds ar
+        WHERE pogs."playerId" = ar."playerId"
+          AND pogs."gameServerId" = ar."gameServerId"
+          AND pogs.domain = ar.domain;
+
+        -- Update order status to CANCELED
+        UPDATE "shopOrder"
+        SET status = 'CANCELED'
+        WHERE "listingId" = NEW.id
+          AND status = 'PAID';
+      END IF;
+
+      RETURN NEW;
+    END;
+    $$ LANGUAGE plpgsql;
+  `);
+
+  // Step 2: Create trigger on shopListing table
+  await knex.raw(`
+    CREATE TRIGGER auto_cancel_orders_on_listing_delete
+    AFTER UPDATE ON "shopListing"
+    FOR EACH ROW
+    WHEN (OLD."deletedAt" IS NULL AND NEW."deletedAt" IS NOT NULL)
+    EXECUTE FUNCTION cancel_orders_on_listing_delete();
+  `);
+}
+
+export async function down(knex: Knex): Promise<void> {
+  // Drop trigger
+  await knex.raw(`
+    DROP TRIGGER IF EXISTS auto_cancel_orders_on_listing_delete ON "shopListing";
+  `);
+
+  // Drop function
+  await knex.raw(`
+    DROP FUNCTION IF EXISTS cancel_orders_on_listing_delete();
+  `);
+
+  // Note: We don't reverse the data cleanup since those were genuinely bad orders
+}

package/src/migrations/sql/20251101000000-add-deleted-domain-state.ts

@@ -0,0 +1,43 @@
+import { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  // PostgreSQL requires a multi-step process to update enum constraints
+  // 1. Add a temporary column with the new enum values
+  // 2. Copy data from old column to new column
+  // 3. Drop old column
+  // 4. Rename new column to old column name
+
+  await knex.schema.alterTable('domains', (table) => {
+    table.enum('state_new', ['ACTIVE', 'DISABLED', 'MAINTENANCE', 'DELETED']).notNullable().defaultTo('ACTIVE');
+  });
+
+  await knex.raw(`UPDATE domains SET state_new = state::text::varchar`);
+
+  await knex.schema.alterTable('domains', (table) => {
+    table.dropColumn('state');
+  });
+
+  await knex.schema.alterTable('domains', (table) => {
+    table.renameColumn('state_new', 'state');
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  // Revert to the original enum values (removing DELETED)
+  // First, ensure no domains are in DELETED state (or this will fail)
+  await knex.raw(`DELETE FROM domains WHERE state = 'DELETED'`);
+
+  await knex.schema.alterTable('domains', (table) => {
+    table.enum('state_new', ['ACTIVE', 'DISABLED', 'MAINTENANCE']).notNullable().defaultTo('ACTIVE');
+  });
+
+  await knex.raw(`UPDATE domains SET state_new = state::text::varchar`);
+
+  await knex.schema.alterTable('domains', (table) => {
+    table.dropColumn('state');
+  });
+
+  await knex.schema.alterTable('domains', (table) => {
+    table.renameColumn('state_new', 'state');
+  });
+}

package/src/migrations/sql/20251108214824-unique-player-per-server.ts

@@ -0,0 +1,30 @@
+import { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  // Delete duplicate rows where the same playerId has multiple different gameIds on the same server
+  // This violates the business rule that each player should have exactly one POG per server
+  // Keep the oldest POG (lowest id) for each (playerId, gameServerId) pair
+  await knex.raw(`
+    DELETE FROM "playerOnGameServer"
+    WHERE id IN (
+      SELECT id
+      FROM (
+        SELECT id,
+               ROW_NUMBER() OVER (PARTITION BY "playerId", "gameServerId" ORDER BY id) as rnk
+        FROM "playerOnGameServer"
+      ) t
+      WHERE t.rnk > 1
+    )
+  `);
+
+  // Add unique constraint to prevent one player from having multiple POGs on the same server
+  await knex.schema.alterTable('playerOnGameServer', (table) => {
+    table.unique(['playerId', 'gameServerId']);
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.alterTable('playerOnGameServer', (table) => {
+    table.dropUnique(['playerId', 'gameServerId']);
+  });
+}

package/src/migrations/util/alterEnum.ts

@@ -0,0 +1,9 @@
+export function formatAlterTableEnumSql(tableName: string, columnName: string, enums: string[]) {
+  const constraintName = `${tableName}_${columnName}_check`;
+  return [
+    `ALTER TABLE "${tableName}" DROP CONSTRAINT IF EXISTS "${constraintName}";`,
+    `ALTER TABLE "${tableName}" ADD CONSTRAINT "${constraintName}" CHECK ("${columnName}" = ANY (ARRAY['${enums.join(
+      "'::text, '",
+    )}'::text]));`,
+  ].join('\n');
+}

package/src/queryBuilder.ts

@@ -0,0 +1,263 @@
+import { IsEnum, IsNumber, IsOptional, IsString } from 'class-validator';
+import { errors } from '@takaro/util';
+import {
+  QueryBuilder as ObjectionQueryBuilder,
+  Model as ObjectionModel,
+  Page,
+  AnyQueryBuilder,
+  Expression,
+  PrimitiveValue,
+} from 'objection';
+import { getKnex, isDbAvailable } from './knex.js';
+
+export class ITakaroQuery<T> {
+  @IsOptional()
+  filters?: {
+    [key: string]: unknown[] | string[] | boolean | null | undefined;
+  };
+
+  @IsOptional()
+  search?: {
+    [key: string]: unknown[] | string[] | boolean | null | undefined;
+  };
+
+  @IsOptional()
+  greaterThan?: {
+    [key in keyof T]?: unknown;
+  };
+
+  @IsOptional()
+  lessThan?: {
+    [key in keyof T]?: unknown;
+  };
+
+  @IsOptional()
+  @IsNumber()
+  page?: number;
+
+  @IsOptional()
+  @IsNumber()
+  limit?: number;
+
+  @IsOptional()
+  @IsString()
+  sortBy?: string;
+
+  @IsOptional()
+  @IsString()
+  @IsEnum(['asc', 'desc'])
+  sortDirection?: SortDirection;
+
+  @IsOptional()
+  @IsString({ each: true })
+  extend?: string[];
+}
+
+export enum SortDirection {
+  asc = 'asc',
+  desc = 'desc',
+}
+
+const modelColumns = new Map<string, string[]>();
+
+export async function populateModelColumns() {
+  if (await isDbAvailable()) {
+    const knex = await getKnex();
+    // Find all tables
+    const tables = await knex.raw(
+      "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public' AND table_type = 'BASE TABLE'",
+    );
+    // For each table, store the columns
+    for (const table of tables.rows) {
+      const tableName = table.table_name;
+      const columns = await knex(tableName).columnInfo();
+      modelColumns.set(tableName, Object.keys(columns));
+    }
+  }
+}
+
+await populateModelColumns();
+
+export class QueryBuilder<Model extends ObjectionModel, OutputDTO> {
+  private query: ITakaroQuery<OutputDTO>;
+  constructor(rawQuery: ITakaroQuery<OutputDTO> = new ITakaroQuery()) {
+    this.query = JSON.parse(JSON.stringify(rawQuery));
+    this.validateArrayFilters();
+  }
+
+  private validateArrayFilters() {
+    // Validate filters
+    if (this.query.filters) {
+      for (const [key, value] of Object.entries(this.query.filters)) {
+        if (value !== null && value !== undefined && !Array.isArray(value) && typeof value !== 'boolean') {
+          throw new errors.BadRequestError(
+            `Filter values must be arrays or boolean. Found invalid value for '${key}': '${value}'. Example: { ${key}: ["${value}"] }`,
+          );
+        }
+      }
+    }
+
+    // Validate search
+    if (this.query.search) {
+      for (const [key, value] of Object.entries(this.query.search)) {
+        if (value !== null && value !== undefined && !Array.isArray(value) && typeof value !== 'boolean') {
+          throw new errors.BadRequestError(
+            `Search values must be arrays or boolean. Found invalid value for '${key}': '${value}'. Example: { ${key}: ["${value}"] }`,
+          );
+        }
+      }
+    }
+  }
+
+  /**
+   * Our custom query builder can only handle columns that exist in the table
+   * However, we might want to do complex/relational logic in higher layers
+   * To make sure we don't error out here, we filter out any columns that don't exist in the current table
+   */
+  private cleanQueryObject(tableName: string) {
+    const columns = modelColumns.get(tableName) ?? [];
+
+    for (const key in this.query.filters) {
+      if (Object.prototype.hasOwnProperty.call(this.query.filters, key)) {
+        if (!columns.includes(key)) {
+          if (this.query.filters) {
+            // Preserve boolean values, only clear arrays
+            if (typeof this.query.filters[key] !== 'boolean') {
+              this.query.filters[key] = [];
+            }
+          }
+        }
+      }
+    }
+
+    for (const key in this.query.search) {
+      if (Object.prototype.hasOwnProperty.call(this.query.search, key)) {
+        if (!columns.includes(key)) {
+          if (this.query.search) {
+            // Preserve boolean values, only clear arrays
+            if (typeof this.query.search[key] !== 'boolean') {
+              this.query.search[key] = [];
+            }
+          }
+        }
+      }
+    }
+
+    return this.query;
+  }
+
+  build(queryBuilder: ObjectionQueryBuilder<Model, Model[]>): ObjectionQueryBuilder<Model, Page<Model>> {
+    const tableName = queryBuilder.modelClass().tableName;
+    this.cleanQueryObject(tableName);
+
+    const pagination = this.pagination();
+    const sorting = this.sorting();
+
+    let qry = queryBuilder.page(pagination.page, pagination.limit).orderBy(sorting.sortBy, sorting.sortDirection);
+
+    qry = this.filters(tableName, qry);
+    qry = this.greaterThan(tableName, qry);
+    qry = this.lessThan(tableName, qry);
+
+    if (this.query.search) {
+      qry.where((builder) => {
+        for (const search in this.query.search) {
+          if (Object.prototype.hasOwnProperty.call(this.query.search, search)) {
+            const searchVal = this.query.search[search];
+            if (Array.isArray(searchVal)) {
+              searchVal.forEach((val) => {
+                if (val) {
+                  builder.orWhere(`${tableName}.${search}`, 'ilike', `%${val}%`);
+                }
+              });
+            }
+          }
+        }
+      });
+    }
+
+    for (const extend of this.query.extend ?? []) {
+      qry.withGraphFetched(extend);
+    }
+
+    return qry;
+  }
+
+  private filters(
+    tableName: string,
+    query: ObjectionQueryBuilder<Model, Page<Model>>,
+  ): ObjectionQueryBuilder<Model, Page<Model>> {
+    for (const filter in this.query.filters) {
+      if (Object.prototype.hasOwnProperty.call(this.query.filters, filter)) {
+        const searchVal = this.query.filters[filter];
+
+        if (typeof searchVal === 'boolean') {
+          query.where(`${tableName}.${filter}`, searchVal);
+        } else if (searchVal && Array.isArray(searchVal)) {
+          if (searchVal.includes('null')) {
+            query.whereNull(`${tableName}.${filter}`);
+            continue;
+          }
+
+          if (searchVal.length) {
+            query.whereIn(`${tableName}.${filter}`, searchVal.filter(Boolean) as unknown as AnyQueryBuilder);
+          }
+        }
+      }
+    }
+
+    return query;
+  }
+
+  private greaterThan(
+    tableName: string,
+    query: ObjectionQueryBuilder<Model, Page<Model>>,
+  ): ObjectionQueryBuilder<Model, Page<Model>> {
+    for (const filter in this.query.greaterThan) {
+      if (Object.prototype.hasOwnProperty.call(this.query.greaterThan, filter)) {
+        const searchVal = this.query.greaterThan[filter];
+        if (searchVal) {
+          query.where(`${tableName}.${filter}`, '>=', searchVal as unknown as Expression<PrimitiveValue>);
+        }
+      }
+    }
+
+    return query;
+  }
+
+  private lessThan(
+    tableName: string,
+    query: ObjectionQueryBuilder<Model, Page<Model>>,
+  ): ObjectionQueryBuilder<Model, Page<Model>> {
+    for (const filter in this.query.lessThan) {
+      if (Object.prototype.hasOwnProperty.call(this.query.lessThan, filter)) {
+        const searchVal = this.query.lessThan[filter];
+        if (searchVal) {
+          query.where(`${tableName}.${filter}`, '<=', searchVal as unknown as Expression<PrimitiveValue>);
+        }
+      }
+    }
+
+    return query;
+  }
+
+  private sorting(): { sortBy: string; sortDirection: SortDirection } {
+    if (!this.query.sortBy) {
+      return {
+        sortBy: 'id',
+        sortDirection: SortDirection.asc,
+      };
+    }
+    return {
+      sortBy: this.query.sortBy,
+      sortDirection: this.query.sortDirection ?? SortDirection.asc,
+    };
+  }
+
+  private pagination() {
+    return {
+      page: this.query.page ?? 0,
+      limit: this.query.limit ?? 100,
+    };
+  }
+}