@cap-js/db-service 2.9.0 → 2.10.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@
 - The format is based on [Keep a Changelog](http://keepachangelog.com/).
 - This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [2.10.0](https://github.com/cap-js/cds-dbs/compare/db-service-v2.9.0...db-service-v2.10.0) (2026-04-22)
+
+
+### Added
+
+* `cds.features.count_as_string` ([#1556](https://github.com/cap-js/cds-dbs/issues/1556)) ([00e0e60](https://github.com/cap-js/cds-dbs/commit/00e0e60d68edf0d42c1fce2fae3bb1286aca131e))
+* **cqn4sql:** support for enums ([#1527](https://github.com/cap-js/cds-dbs/issues/1527)) ([27c4279](https://github.com/cap-js/cds-dbs/commit/27c4279c495fce8344c785e4489e3116d1a52c55))
+* pql ([#1532](https://github.com/cap-js/cds-dbs/issues/1532)) ([943f76a](https://github.com/cap-js/cds-dbs/commit/943f76a3e4405eb91f0f4b929590212500c49c30))
+
+
+### Fixed
+
+* `$self` reference to func column in `having` ([#1539](https://github.com/cap-js/cds-dbs/issues/1539)) ([9eac576](https://github.com/cap-js/cds-dbs/commit/9eac5762fc4d254a1bc54bded1dd6a492299f576)), closes [#1528](https://github.com/cap-js/cds-dbs/issues/1528)
+* foreign key not included in wildcard select from subquery ([#1540](https://github.com/cap-js/cds-dbs/issues/1540)) ([0fde4ed](https://github.com/cap-js/cds-dbs/commit/0fde4eda21a389c68982f348e9e7c3680c00dcb3)), closes [#1127](https://github.com/cap-js/cds-dbs/issues/1127)
+* sqlite generated key is named lastInsertRowid ([#1501](https://github.com/cap-js/cds-dbs/issues/1501)) ([a4d3437](https://github.com/cap-js/cds-dbs/commit/a4d34378297c8afdb13abb7e664165012c36eb8f))
+
 ## [2.9.0](https://github.com/cap-js/cds-dbs/compare/db-service-v2.8.2...db-service-v2.9.0) (2026-03-09)
 
 

package/lib/InsertResults.js

@@ -69,9 +69,12 @@ module.exports = class InsertResult {
     }
 
     // If no generated keys in entries/rows/values we might have database-generated keys
-    const rows = this.results.slice(0, this.affectedRows) // only up to # of root entries
     return (super[iterator] = function* () {
-      for (const each of rows) yield { [k1]: this.insertedRowId4(each) } // REVISIT: sqlite only returns a single lastID per row -> how is that with others?
+      for (const row of this.results) {
+        const affectedRows = this.affectedRows4(row) - 1
+        const lastInsertRowid = this.insertedRowId4(row)
+        for (let i = lastInsertRowid - affectedRows; i<=lastInsertRowid;i++) yield { [k1]: i }
+      }
     })
   }
 
@@ -99,7 +102,7 @@ module.exports = class InsertResult {
    * @returns {number}
    */
   insertedRowId4(result) {
-    return result.lastID
+    return result.lastInsertRowid
   }
 
   /**

package/lib/SQLService.js

@@ -1,11 +1,15 @@
-const cds = require('@sap/cds'),
-  DEBUG = cds.debug('sql|db')
+const cds = require('@sap/cds')
+const DEBUG = cds.log('sql|db')
 const { Readable, Transform } = require('stream')
 const { pipeline } = require('stream/promises')
 const DatabaseService = require('./common/DatabaseService')
 const cqn4sql = require('./cqn4sql')
 const { resolveTable } = require('./utils')
 
+// REVISIT: make string the default in next major
+const _count_as_string = cds.env.features.count_as_string
+const _count = _count_as_string ? { func: 'count', cast: { type: 'cds.String' } } : { func: 'count' }
+
 const BINARY_TYPES = {
   'cds.Binary': 1,
   'cds.hana.BINARY': 1
@@ -17,7 +21,7 @@ const BINARY_TYPES = {
  * @param {*} obj 
  * @returns Boolean
  */
-const _hasProps = (obj) => { 
+const _hasProps = (obj) => {
   if (!obj) return false
   for (const p in obj) {
     return true
@@ -74,7 +78,7 @@ class SQLService extends DatabaseService {
   _changeToStreams(columns, rows, one) {
     if (!rows || !columns) return
     if (!Array.isArray(rows)) rows = [rows]
-    if (!rows.length || !Object.keys(rows[0]).length) return   
+    if (!rows.length || !Object.keys(rows[0]).length) return
 
     let changes = false
     for (let col of columns) {
@@ -149,7 +153,7 @@ class SQLService extends DatabaseService {
         if (expand) rows = rows.map(r => (typeof r._json_ === 'string' ? JSON.parse(r._json_) : r._json_ || r))
 
       if (!iterator) {
-         this._changeToStreams(cqn.SELECT.columns, rows, query.SELECT.one)
+        this._changeToStreams(cqn.SELECT.columns, rows, query.SELECT.one)
       } else if (objectMode) {
         const converter = (row) => this._changeToStreams(cqn.SELECT.columns, row, true)
         const changeToStreams = new Transform({
@@ -198,7 +202,7 @@ class SQLService extends DatabaseService {
     const ps = await this.prepare(sql)
     const results = entries ? await Promise.all(entries.map(e => ps.run(e))) : await ps.run()
     // REVISIT: results isn't an array, when no entries -> how could that work? when do we have no entries?
-    return results.reduce((total, affectedRows) => (total += affectedRows.changes), 0)
+    return results.reduce((total, affectedRows) => total + affectedRows.changes, 0)
   }
 
   /**
@@ -296,7 +300,7 @@ class SQLService extends DatabaseService {
    * @type {Handler}
    */
   async onEVENT({ event }) {
-    DEBUG?.(event) // in the other cases above DEBUG happens in cqn2sql
+    if(DEBUG._debug) DEBUG.debug(event) // in the other cases above DEBUG happens in cqn2sql
     return await this.exec(event)
   }
 
@@ -306,7 +310,7 @@ class SQLService extends DatabaseService {
    */
   async onPlainSQL({ query, data }, next) {
     if (typeof query === 'string') {
-      DEBUG?.(query, data)
+      if(DEBUG._debug) DEBUG.debug(query, data)
       const ps = await this.prepare(query)
       const exec = this.hasResults(query) ? d => ps.all(d) : d => ps.run(d)
       if (Array.isArray(data) && Array.isArray(data[0])) return await Promise.all(data.map(exec))
@@ -326,24 +330,24 @@ class SQLService extends DatabaseService {
    * Derives and executes a query to fill in `$count` for given query
    * @param {import('@sap/cds/apis/cqn').SELECT} query - SELECT CQN
    * @param {unknown[]} ret - Results of the original query
-   * @returns {Promise<number>}
+   * @returns {Promise<number|string>}
    */
   async count(query, ret) {
     if (ret?.length) {
       const { one, limit: _ } = query.SELECT,
         n = ret.length
       const [max, offset = 0] = one ? [1] : _ ? [_.rows?.val, _.offset?.val] : []
-      if (max === undefined || (n < max && (n || !offset))) return n + offset
+      if (max === undefined || (n < max && (n || !offset))) return _count_as_string ? `${n + offset}` : n + offset
     }
 
     // Keep original query columns when potentially used insde conditions
     const { having, groupBy } = query.SELECT
     let columns = []
-    if((having?.length || groupBy?.length)) {
+    if (having?.length || groupBy?.length) {
       columns = query.SELECT.columns.filter(c => !c.expand)
     }
     if (columns.length === 0) columns.push({ val: 1 })
-    const cq = SELECT.one([{ func: 'count' }]).from(
+    const cq = SELECT.one([_count]).from(
       cds.ql.clone(query, {
         columns,
         localized: false,
@@ -361,7 +365,7 @@ class SQLService extends DatabaseService {
    * @param {import('@sap/cds/apis/cqn').SELECT} query - SELECT CQN
    * @param {function} callback - Function to be invoked for each row
    */
-  foreach (query, callback) {
+  foreach(query, callback) {
     return query.foreach(callback)
   }
 
@@ -391,36 +395,34 @@ class SQLService extends DatabaseService {
     })
   }
 
-  /** @param {unknown[]} args */
   constructor(...args) {
     super(...args)
-    /** @type {unknown} */
     this.class = new.target // for IntelliSense
   }
 
   /**
    * @param {import('@sap/cds/apis/cqn').Query} query
-   * @param {unknown} values
    * @returns {typeof SQLService.CQN2SQL}
    */
   cqn2sql(query, values) {
-    let q = this.cqn4sql(query)
-    let cqn2sql = new this.class.CQN2SQL(this)
-    return cqn2sql.render(q, values)
+    const cqn2sql = new this.class.CQN2SQL(this)
+    const q = this.cqn4sql(query)
+    const sql = cqn2sql.render(q, values)
+    return sql
   }
 
   /**
    * @param {import('@sap/cds/apis/cqn').Query} q
    * @returns {import('./infer/cqn').Query}
    */
-  cqn4sql(q) {
+  cqn4sql(q, useTechnicalAlias=true) {
     if (
       !cds.env.features.db_strict &&
       !q.SELECT?.from?.join &&
       !q.SELECT?.from?.SELECT &&
       !this.model?.definitions[_target_name4(q)]
     ) return q
-    else return cqn4sql(q, this.model)
+    else return cqn4sql(q, this.model, useTechnicalAlias)
   }
 
   /**
@@ -509,31 +511,70 @@ const _target_name4 = q => {
   return first.id || first
 }
 
-const sqls = new (class extends SQLService {
-  get factory() {
-    return null
-  }
 
-  get model() {
-    return cds.model
+// Add support for cqn2pql if debug logging for pql is enabled, or if running in the REPL.
+const DEBUG_PQL = cds.log('pql')
+if (DEBUG_PQL._debug || cds.repl) {
+
+  // Add helper method to convert CQN to PQL, used below...
+  SQLService.prototype.cqn2pql = function cqn2pql (query, values) {
+    const CQN2PQL = cqn2pql.renderer ??= require('./cqn2pql')
+    return new CQN2PQL(this).render(query, values)
   }
-})()
-cds.extend(cds.ql.Query).with(
-  class {
-    forSQL() {
-      let cqn = (cds.db || sqls).cqn4sql(this)
-      return this.flat(cqn)
-    }
-    toSQL() {
-      if (this.SELECT) this.SELECT.expand = 'root' // Enforces using json functions always for top-level SELECTS
-      let { sql, values } = (cds.db || sqls).cqn2sql(this)
-      return { sql, values } // skipping .cqn property
+
+  // Add support for logging generated PQL if debug logging for pql is enabled.
+  if (DEBUG_PQL._debug) {
+    const $super = SQLService.prototype.cqn2sql
+    SQLService.prototype.cqn2sql = function (query, values) {
+      const q2 = this.cqn4sql(query, false) // FIXME: calling cqn4sql twice per query is utterly expensive, isn't it ?!?
+      const pql = this.cqn2pql(q2, values)
+      DEBUG_PQL.debug(pql.sql, pql.values ?? '')
+      return $super.call(this, query, values)
     }
-    toSql() {
-      return this.toSQL().sql
+  }
+
+  // If running in the REPL, extend cds.ql.Query with helpers to inspect queries. 
+  if (cds.repl) {
+
+    cds.extend(cds.ql.Query).with(
+      class {
+        forSQL() {
+          const cqn = db.srv.cqn4sql(this)
+          return this.flat(cqn)
+        }
+        forSql() { return this.forSQL() }
+        toSQL() {
+          if (this.SELECT) this.SELECT.expand = 'root' // Enforces using json functions always for top-level SELECTS
+          const { sql, values } = db.srv.cqn2sql(this)
+          return { sql, values } // skipping .cqn property
+        }
+        toSql() {
+          const { sql } = this.toSQL()
+          return sql
+        }
+        toPQL() {
+          const { sql, values } = db.srv.cqn2pql(this)
+          return { sql, values } // skipping .cqn property
+        }
+        toPql() {
+          const { sql } = this.toPQL()
+          return sql
+        }
+      }
+    )
+
+    /** 
+     * Dummy SQL service used in extensions to cds.ql above, 
+     * if no real SQL service is available yet through cds.db. 
+     */
+    class db extends SQLService {
+      /** @returns {SQLService} */ 
+      static get srv() { return cds.db || (this.singleton ??= new this) }
+      get factory() { return null }
+      get model() { return cds.model }
     }
-  },
-)
+  }
+}
 
 Object.assign(SQLService, { _target_name4 })
 module.exports = SQLService

package/lib/cql-functions.js

@@ -293,7 +293,7 @@ SELECT
     (SELECT MAX(HIERARCHY_RANK) + 1 FROM ${ranked})
   ) - Source.HIERARCHY_RANK AS HIERARCHY_TREE_SIZE
  FROM ${ranked} AS Source`)
-    Hierarchy.as = 'H' + (uniqueCounter++)
+    Hierarchy.as = `H${uniqueCounter}`
     Hierarchy.SELECT.columns = [...Hierarchy.SELECT.columns, ...passThroughColumns]
     Hierarchy = this.expr(this.with(Hierarchy))
 

package/lib/cqn2pql.js

@@ -0,0 +1,116 @@
+const cds = require('@sap/cds')
+
+const CQN2SQL = require('./cqn2sql.js').class
+
+class CQN2PQLRenderer extends CQN2SQL {
+
+  SELECT(q) {
+    this.values = undefined // inline all values
+    return (this.sql = super.SELECT(q)
+      .replaceAll('\n FROM', '\nFROM')
+      .replaceAll(/([^ ]) (FROM|WHERE|GROUP BY|HAVING|ORDER BY|LIMIT) /g, (a, b, c) => `${b}\n${c} `)
+    )
+  }
+
+  SELECT_columns(q) {
+    return super.SELECT_columns(q).map((c, i) => `${(i % 5 === 0) ? '\n  ' : ' '}${c}${/ as /i.test(c) ? '\n' : ''}`).join(',')
+  }
+
+  column_expr(x, q) {
+    // omit alias when target is a single source
+    if (q.SELECT.from.ref && x?.ref) x.ref = x.ref.slice(-1)
+    return super.column_expr(x, q)
+  }
+
+  SELECT_expand(q, sql) { return sql }
+
+  INSERT_entries(q) {
+    super.INSERT_entries(q)
+    this.sql = this.sql
+      .replaceAll(/AS (.*?)([, ])(?=[^\n])/ig, (a, b, c) => `AS ${b}${c}\n${c === ',' ? ' ' : ''}`)
+      .replaceAll(/ *= */ig, ' = ')
+      .replaceAll('value AS "$$value$$"', 'value')
+      .replaceAll(' WHERE ', '\nWHERE ')
+      .replaceAll(' SELECT ', '\nSELECT')
+      .replaceAll('(SELECT ', '(SELECT\n  ')
+      .replaceAll('))', ')\n)')
+  }
+
+  INSERT_rows(q) {
+    super.INSERT_rows(q)
+    this.sql = this.sql.replaceAll('SELECT', '\nSELECT')
+  }
+
+  UPSERT(q) {
+    super.UPSERT(q)
+    this.sql = this.sql
+      .replaceAll('INSERT', 'UPSERT')
+      .replaceAll(/AS (.*?)([, ])(?=[^\n])/ig, (a, b, c) => `AS ${b}${c}\n${c === ',' ? ' ' : ''}`)
+      .replaceAll(/ *= */ig, ' = ')
+      .replaceAll('value AS "$$value$$"', 'value')
+      .replaceAll(' WHERE ', '\nWHERE ')
+      .replaceAll(' SELECT ', '\nSELECT')
+      .replaceAll('(SELECT ', '(SELECT\n  ')
+      .replaceAll('))', ')\n)')
+  }
+
+  expr(x) {
+    const wrap = x.cast ? sql => `cast(${sql} as ${this.type4(x.cast)})` : sql => sql
+    if (typeof x === 'string') throw cds.error`Unsupported expr: ${x}`
+    if (x.param) return wrap(this.param(x))
+    if ('ref' in x) return wrap(this.ref(x))
+    if ('val' in x) return wrap(this.val(x))
+    if ('func' in x) return wrap(this.func(x))
+    if ('xpr' in x) return wrap(this.xpr(x))
+    if ('list' in x) return wrap(this.list(x))
+    if ('SELECT' in x) return wrap(`(\n    ${this.SELECT(x).replaceAll('\n', '\n    ')}\n  )`)
+    else throw cds.error`Unsupported expr: ${x}`
+  }
+
+  quote(s) { return s }
+
+  managed(columns, elements) {
+    const keys = ObjectKeys(elements).filter(e => elements[e].key && !elements[e].isAssociation)
+    const keyZero = keys[0]
+
+    const ret = super.managed(columns, elements)
+
+    ret.forEach(c => {
+      const { name, insert, update, onInsert, onUpdate } = c
+      const element = elements?.[name]
+      c.upsert = keyZero && (
+        // upsert requires the keys to be provided for the existance join (default values optional)
+        element?.key
+          // If both insert and update have the same managed definition exclude the old value check
+          || (onInsert && onUpdate && insert === update)
+          ? `${insert} as ${name}`
+          : `!OLD.${keyZero} ? ${
+          // If key of old is null execute insert
+          insert
+          } : ${
+          // Else execute managed update or keep old if no new data if provided
+          onUpdate ? update : `(${this.managed_default(name, `OLD.${name}`, update)})`
+          } as ${name}`
+      )
+      if (c.upsert) c.upsert = '\n  ' + c.upsert
+    })
+    return ret
+  }
+
+  managed_default(name, managed, src) {
+    return `!${src} ? ${managed} : ${src}`
+  }
+
+  managed_extract(name) {
+    const { UPSERT, INSERT } = this.cqn
+    const extract = !(INSERT?.entries || UPSERT?.entries) && (INSERT?.rows || UPSERT?.rows)
+      ? `value[${this.columns.indexOf(name)}]`
+      : `value[${JSON.stringify(name)}]`
+    const sql = extract
+    return { extract, sql }
+  }
+}
+
+const ObjectKeys = o => (o && [...ObjectKeys(o.__proto__), ...Object.keys(o)]) || []
+
+module.exports = CQN2PQLRenderer

package/lib/cqn2sql.js

@@ -5,12 +5,13 @@ const { resolveTable } = require('./utils')
 
 const _simple_queries = cds.env.features.sql_simple_queries
 const _strict_booleans = _simple_queries < 2
+// REVISIT: make string the default in next major
+const _count_as_string = cds.env.features.count_as_string
+const _count = _count_as_string ? { func: 'count', cast: { type: 'cds.String' } } : { func: 'count' }
 
 const { Readable } = require('stream')
 
-const DEBUG = cds.debug('sql|sqlite')
-const LOG_SQL = cds.log('sql')
-const LOG_SQLITE = cds.log('sqlite')
+const DEBUG = cds.log('sql|sqlite')
 
 class CQN2SQLRenderer {
   /**
@@ -94,12 +95,12 @@ class CQN2SQLRenderer {
     if (vars && Object.keys(vars).length && !this.values?.length) this.values = vars
     const sanitize_values = process.env.NODE_ENV === 'production' && cds.env.log.sanitize_values !== false
 
-    if (DEBUG && (LOG_SQL._debug || LOG_SQLITE._debug)) {
+    if (DEBUG._debug) {
       let values = sanitize_values && (this.entries || this.values?.length > 0) ? ['***'] : this.entries || this.values || []
       if (values && !Array.isArray(values)) {
         values = [values]
       }
-      DEBUG(this.sql, values)
+      DEBUG.debug(this.sql, values)
     }
 
     return this
@@ -657,7 +658,7 @@ class CQN2SQLRenderer {
 
   SELECT_count(q) {
     const countQuery = cds.ql.clone(q, {
-      columns: [{ func: 'count' }],
+      columns: [_count],
       one: 0, limit: 0, orderBy: 0, expand: 0, count: 0
     })
     countQuery.as = q.as + '@odata.count'

package/lib/cqn4sql.js

@@ -9,7 +9,7 @@ const {
   prettyPrintRef,
   isCalculatedOnRead,
   isCalculatedElement,
-  getImplicitAlias,
+  getImplicitAlias: _getImplicitAlias,
   defineProperty,
   getModelUtils,
   hasOwnSkip,
@@ -54,7 +54,8 @@ const { pseudos } = require('./infer/pseudos')
  * @param {object} model
  * @returns {object} transformedQuery the transformed query
  */
-function cqn4sql(originalQuery, model) {
+function cqn4sql(originalQuery, model, useTechnicalAlias = true) {
+  const getImplicitAlias = str => _getImplicitAlias(str, useTechnicalAlias)
   let inferred = typeof originalQuery === 'string' ? cds.parse.cql(originalQuery) : cds.ql.clone(originalQuery)
   const hasCustomJoins =
     originalQuery.SELECT?.from.args && (!originalQuery.joinTree || originalQuery.joinTree.isInitial)
@@ -81,7 +82,7 @@ function cqn4sql(originalQuery, model) {
   if (inferred.UPDATE?.entity.ref?.at(-1).id) {
     assignQueryModifiers(inferred.UPDATE, inferred.UPDATE.entity.ref.at(-1))
   }
-  inferred = infer(inferred, model)
+  inferred = infer(inferred, model, useTechnicalAlias)
   const { getLocalizedName, isLocalized, getDefinition } = getModelUtils(model, originalQuery) // TODO: pass model to getModelUtils
   // if the query has custom joins we don't want to transform it
   // TODO: move all the way to the top of this function once cds.infer supports joins as well
@@ -134,7 +135,7 @@ function cqn4sql(originalQuery, model) {
       // match primary keys of the target entity with the subquery
       primaryKey.list.forEach(k => subquery.SELECT.columns.push({ ref: k.ref.slice(1) }))
 
-      const transformedSubquery = cqn4sql(subquery, model)
+      const transformedSubquery = cqn4sql(subquery, model, useTechnicalAlias)
 
       // replace where condition of original query with the transformed subquery
       // correlate UPDATE / DELETE query with subquery by primary key matches
@@ -229,9 +230,9 @@ function cqn4sql(originalQuery, model) {
         }
       }
     }
-    const inferredDQ = infer(q, model)
+    const inferredDQ = infer(q, model, useTechnicalAlias)
     inferredDQ._with = transformedQuery._with
-    const transformedDQ = cqn4sql(inferredDQ, model)
+    const transformedDQ = cqn4sql(inferredDQ, model, useTechnicalAlias)
 
     if (q.SELECT?.from?.args) {
       for (const arg of q.SELECT.from.args) {
@@ -622,6 +623,11 @@ function cqn4sql(originalQuery, model) {
 
     function getTransformedColumn(col) {
       let ret
+      if (col !== null && typeof col === 'object' && '#' in col) {
+        ret = resolveEnumToken(col, [], -1)
+        // cast is already resolved inside resolveEnumToken; do not overwrite it here
+        return ret
+      }
       if (col.func) {
         ret = {
           func: col.func,
@@ -634,7 +640,7 @@ function cqn4sql(originalQuery, model) {
         ret.xpr = getTransformedTokenStream(col.xpr)
       }
       if (ret) {
-        if (col.cast) ret.cast = col.cast
+        if (col.cast) ret.cast = resolveEnumCastType(col.cast)
         return ret
       }
       return copy(col)
@@ -726,10 +732,11 @@ function cqn4sql(originalQuery, model) {
           },
         })
       } else {
-        // target column is `val` or `xpr`, destructure and throw away the ref with the $self
+        // target column is `val`, `xpr`, or `func` — destructure and throw away the ref with the $self
         // eslint-disable-next-line no-unused-vars
-        const { xpr, val, ref, as: _as, ...rest } = referencedColumn
+        const { xpr, val, func, args, ref, as: _as, ...rest } = referencedColumn
         if (xpr) rest.xpr = xpr
+        else if (func) { rest.func = func; rest.args = args }
         else rest.val = val
         dollarSelfColumn = { ...rest } // reassign dummyColumn without 'ref'
         if (!omitAlias) dollarSelfColumn.as = as
@@ -836,9 +843,11 @@ function cqn4sql(originalQuery, model) {
           return { ...token, xpr: augmentInlineXprRefs(token.xpr, parentCol) }
         }
         if (token.func && token.args) {
-          return { ...token, args: token.args.map(arg => 
-            arg.ref ? augmentInlineXprRefs([arg], parentCol)[0] : arg
-          )}
+          return {
+            ...token, args: token.args.map(arg =>
+              arg.ref ? augmentInlineXprRefs([arg], parentCol)[0] : arg
+            )
+          }
         }
         return token
       })
@@ -1347,7 +1356,7 @@ function cqn4sql(originalQuery, model) {
     if (isLocalized(target)) q.SELECT.localized = true
     if (q.SELECT.from.ref && !q.SELECT.from.as) assignUniqueSubqueryAlias()
     if (cds.env.features.runtime_views) q._with = transformedQuery._with
-    const _q = cqn4sql(q, model)
+    const _q = cqn4sql(q, model, useTechnicalAlias)
     if (cds.env.features.runtime_views && _q._with) {
       if (!transformedQuery._with) transformedQuery._with = _q._with
       delete _q._with
@@ -1388,8 +1397,8 @@ function cqn4sql(originalQuery, model) {
       if (!exclude.includes(k)) {
         const { index, tableAlias } = inferred.$combinedElements[k][0]
         const element = tableAlias.elements[k]
-        // ignore FK for odata csn / ignore blobs from wildcard expansion
-        if (isManagedAssocInFlatMode(element) || element.type === 'cds.LargeBinary') continue
+        // ignore FK for odata csn (but not for subquery sources where FK is not a separate element) / ignore blobs from wildcard expansion
+        if ((!tableAlias.SELECT && isManagedAssocInFlatMode(element)) || element.type === 'cds.LargeBinary') continue
         // for wildcard on subquery in from, just reference the elements
         if (tableAlias.SELECT && !element.elements && !element.target) {
           wildcardColumns.push(index ? { ref: [index, k] } : { ref: [k] })
@@ -1437,35 +1446,23 @@ function cqn4sql(originalQuery, model) {
 
   /**
    * Recursively expands a structured element into flat columns, representing all leaf paths.
-   * This function transforms complex structured elements into simple column representations.
    *
-   * For each element, the function checks if it's a structure, an association or a scalar,
-   * and proceeds accordingly. If the element is a structure, it recursively fetches flat columns for all sub-elements.
-   * If it's an association, it fetches flat columns for it's foreign keys.
-   * If it's a scalar, it creates a flat column for it.
+   * Structures → flat sub-element columns. Associations → flat foreign key columns.
+   * Scalars → single column reference.
    *
-   * Columns excluded in a wildcard expansion or replaced by other columns are also handled accordingly.
-   *
-   * @param {object} column - The structured element which needs to be expanded.
+   * @param {object} column - The element to expand (may be a ref with $refLinks, or a raw element definition).
    * @param {{
-   *  columnAlias: string
-   *  tableAlias: string
-   *  baseName: string
-   * }} names - configuration object for naming parameters:
-   * columnAlias - The explicit alias which the user has defined for the column.
-   *                               For instance `{ struct.foo as bar}` will be transformed into
-   *                               `{ struct_foo_leaf1 as bar_foo_leaf1, struct_foo_leaf2 as bar_foo_leaf2 }`.
-   * tableAlias - The table alias to prepend to the column name. Optional.
-   * baseName - The prefixes of the column reference (joined with '_'). Optional.
-   * @param {string} columnAlias - The explicit alias which the user has defined for the column.
-   *                               For instance `{ struct.foo as bar}` will be transformed into
-   *                               `{ struct_foo_leaf1 as bar_foo_leaf1, struct_foo_leaf2 as bar_foo_leaf2 }`.
-   * @param {string} tableAlias - The table alias to prepend to the column name. Optional.
-   * @param {Array} csnPath - An array containing CSN paths. Optional.
-   * @param {Array} exclude - An array of columns to be excluded from the flat structure. Optional.
-   * @param {Array} replace - An array of columns to be replaced in the flat structure. Optional.
-   *
-   * @returns {object[]} Returns an array of flat column(s) for the given element.
+   *  baseName?: string,
+   *  columnAlias?: string,
+   *  tableAlias?: string
+   * }} [names] - Naming context:
+   *   - `baseName` — accumulated underscore-joined prefix for the flat column ref (e.g. `'address'` → `'address_street'`).
+   *   - `columnAlias` — explicit alias for the output column. Defaults to `column.as` when omitted.
+   *   - `tableAlias` — table alias prepended to the column ref.
+   * @param {string[]} [csnPath=[]] - Accumulated CSN element path (used for `_csnPath` metadata on leaf columns).
+   * @param {{ exclude?: Array, replace?: Array }} [excludeAndReplace] - Columns to exclude or replace during wildcard expansion.
+   * @param {boolean} [isWildcard=false] - Whether this expansion originates from a wildcard; filters out LargeBinary.
+   * @returns {object[]} Flat column(s) for the given element.
    */
   function getFlatColumnsFor(column, names, csnPath = [], excludeAndReplace, isWildcard = false) {
     if (!column) return column
@@ -1478,28 +1475,13 @@ function cqn4sql(originalQuery, model) {
     let firstNonJoinRelevantAssoc, stepAfterAssoc
     let element = $refLinks ? $refLinks[$refLinks.length - 1].definition : column
     if (isWildcard && element.type === 'cds.LargeBinary') return []
-    if (element.on && !element.keys)
-      return [] // unmanaged doesn't make it into columns
-    else if (element.virtual === true) return []
-    else if (!isJoinRelevant && flatName) baseName = flatName
-    else if (isJoinRelevant) {
-      const leafAssocIndex = column.$refLinks.findIndex(link => link.definition.isAssociation && link.onlyForeignKeyAccess)
-      firstNonJoinRelevantAssoc = column.$refLinks[leafAssocIndex] || [...column.$refLinks].reverse().find(link => link.definition.isAssociation)
-      stepAfterAssoc = column.$refLinks.at(leafAssocIndex + 1) || column.$refLinks.at(-1)
-      let elements = firstNonJoinRelevantAssoc.definition.elements || firstNonJoinRelevantAssoc.definition.foreignKeys
-      if (elements && stepAfterAssoc.definition.name in elements) {
-        element = firstNonJoinRelevantAssoc.definition
-        baseName = getFullName(firstNonJoinRelevantAssoc.definition)
-        columnAlias = column.as || column.ref.slice(0, -1).map(idOnly).join('_')
-      } else baseName = getFullName(column.$refLinks[column.$refLinks.length - 1].definition)
-
-      if (column.element && !isAssocOrStruct(column.element)) {
-        columnAlias = column.as || leafAssocIndex === -1 ? columnAlias : column.ref.slice(leafAssocIndex - 1).map(idOnly).join('_')
-        const res = { ref: [tableAlias, calculateElementName(column)], as: columnAlias }
-        setElementOnColumns(res, column.element)
-        return [res]
-      }
+    if (element.on && !element.keys) return [] // unmanaged doesn't make it into columns
+    if (element.virtual === true) return []
 
+    if (!isJoinRelevant && flatName) baseName = flatName
+    else if (isJoinRelevant) {
+      const earlyResult = resolveJoinRelevantNames()
+      if (earlyResult) return earlyResult
     } else if (!baseName && structsAreUnfoldedAlready) {
       baseName = element.name // name is already fully constructed
     } else {
@@ -1530,108 +1512,41 @@ function cqn4sql(originalQuery, model) {
       return getFlatColumnsFor(replacedBy, { baseName, columnAlias: replacedBy.as, tableAlias }, csnPath)
     }
 
-    csnPath.push(element.name)
+    csnPath = [...csnPath, element.name]
 
-    if (element.keys) {
-      const flatColumns = []
-      for (const k of element.keys) {
-        // if only one part of a foreign key is requested, only flatten the partial key
-        const keyElement = getElementForRef(k.ref, getDefinition(element.target))
-        const flattenThisForeignKey =
-          !$refLinks || // the association is passed as element, not as ref --> flatten full foreign key
-          element === $refLinks.at(-1).definition || // the association is the leaf of the ref --> flatten full foreign key
-          keyElement === stepAfterAssoc.definition // the foreign key is the leaf of the ref --> only flatten this specific foreign key
-        if (flattenThisForeignKey) {
-          const fkElement = getElementForRef(k.ref, getDefinition(element.target))
-          let fkBaseName
-          if (!firstNonJoinRelevantAssoc || firstNonJoinRelevantAssoc.onlyForeignKeyAccess) fkBaseName = `${baseName}_${k.as || k.ref.at(-1)}`
-          // e.g. if foreign key is accessed via infix filter - use join alias to access key in target
-          else fkBaseName = k.ref.at(-1)
-          const fkPath = [...csnPath, k.ref.at(-1)]
-          if (fkElement.elements) {
-            // structured key
-            for (const e of Object.values(fkElement.elements)) {
-              let alias
-              if (columnAlias) {
-                const fkName = k.as
-                  ? `${k.as}_${e.name}` // foreign key might also be re-named: `assoc { id as foo }`
-                  : `${k.ref.join('_')}_${e.name}`
-                alias = `${columnAlias}_${fkName}`
-              }
-              flatColumns.push(
-                ...getFlatColumnsFor(
-                  e,
-                  { baseName: fkBaseName, columnAlias: alias, tableAlias },
-                  [...fkPath],
-                  excludeAndReplace,
-                  isWildcard,
-                ),
-              )
-            }
-          } else if (fkElement.isAssociation) {
-            // assoc as key
-            flatColumns.push(
-              ...getFlatColumnsFor(
-                fkElement,
-                { baseName, columnAlias, tableAlias },
-                csnPath,
-                excludeAndReplace,
-                isWildcard,
-              ),
-            )
-          } else {
-            // leaf reached
-            let flatColumn
-            if (columnAlias) {
-              // if the column has an explicit alias AND the original ref
-              // directly resolves to the foreign key, we must not append the fk name to the column alias
-              // e.g. `assoc.fk as FOO` => columns.alias = FOO
-              //      `assoc as FOO`    => columns.alias = FOO_fk
-              let columnAliasWithFlatFk
-              if (!(column.as && fkElement === column.$refLinks?.at(-1).definition))
-                columnAliasWithFlatFk = `${columnAlias}_${k.as || k.ref.join('_')}`
-              flatColumn = { ref: [fkBaseName], as: columnAliasWithFlatFk || columnAlias }
-            } else flatColumn = { ref: [fkBaseName] }
-            if (tableAlias) flatColumn.ref.unshift(tableAlias)
-
-            // in a flat model, we must assign the foreign key rather than the key in the target
-            const flatForeignKey = getDefinition(element.parent.name)?.elements[fkBaseName]
-
-            setElementOnColumns(flatColumn, flatForeignKey || fkElement)
-            defineProperty(flatColumn, '_csnPath', csnPath)
-            flatColumns.push(flatColumn)
-          }
-        }
-      }
-      return flatColumns
-    } else if (element.elements && element.type !== 'cds.Map') {
+    if (element.keys) return flattenForeignKeys()
+    if (element.elements && element.type !== 'cds.Map') return flattenStructElements()
+    return buildScalarColumn()
+
+    function flattenStructElements() {
       const flatRefs = []
-      Object.values(element.elements).forEach(e => {
+      for (const e of Object.values(element.elements)) {
         const alias = columnAlias ? `${columnAlias}_${e.name}` : null
         flatRefs.push(
           ...getFlatColumnsFor(
             e,
             { baseName, columnAlias: alias, tableAlias },
-            [...csnPath],
+            csnPath,
             excludeAndReplace,
             isWildcard,
           ),
         )
-      })
+      }
       return flatRefs
     }
-    const flatRef = tableAlias ? { ref: [tableAlias, baseName] } : { ref: [baseName] }
-    if (column.cast) {
-      flatRef.cast = column.cast
-      if (!columnAlias)
-        // provide an explicit alias
-        columnAlias = baseName
+
+    function buildScalarColumn() {
+      const flatRef = tableAlias ? { ref: [tableAlias, baseName] } : { ref: [baseName] }
+      if (column.cast) {
+        flatRef.cast = column.cast
+        if (!columnAlias) columnAlias = baseName
+      }
+      if (column.sort) flatRef.sort = column.sort
+      if (columnAlias) flatRef.as = columnAlias
+      setElementOnColumns(flatRef, element)
+      defineProperty(flatRef, '_csnPath', csnPath)
+      return [flatRef]
     }
-    if (column.sort) flatRef.sort = column.sort
-    if (columnAlias) flatRef.as = columnAlias
-    setElementOnColumns(flatRef, element)
-    defineProperty(flatRef, '_csnPath', csnPath)
-    return [flatRef]
 
     function getReplacement(from) {
       return from?.find(replacement => {
@@ -1639,6 +1554,101 @@ function cqn4sql(originalQuery, model) {
         return nameOfExcludedColumn === element.name
       })
     }
+
+    function resolveJoinRelevantNames() {
+      const leafAssocIndex = column.$refLinks.findIndex(
+        link => link.definition.isAssociation && link.onlyForeignKeyAccess,
+      )
+      firstNonJoinRelevantAssoc =
+        column.$refLinks[leafAssocIndex] || [...column.$refLinks].reverse().find(link => link.definition.isAssociation)
+      stepAfterAssoc = column.$refLinks.at(leafAssocIndex + 1) || column.$refLinks.at(-1)
+      const targetElements = firstNonJoinRelevantAssoc.definition.elements || firstNonJoinRelevantAssoc.definition.foreignKeys
+      if (targetElements && stepAfterAssoc.definition.name in targetElements) {
+        element = firstNonJoinRelevantAssoc.definition
+        baseName = getFullName(firstNonJoinRelevantAssoc.definition)
+        columnAlias = column.as || column.ref.slice(0, -1).map(idOnly).join('_')
+      } else {
+        baseName = getFullName(column.$refLinks.at(-1).definition)
+      }
+
+      if (column.element && !isAssocOrStruct(column.element)) {
+        columnAlias =
+          column.as || (leafAssocIndex === -1 ? columnAlias : column.ref.slice(leafAssocIndex - 1).map(idOnly).join('_'))
+        const res = { ref: [tableAlias, calculateElementName(column)], as: columnAlias }
+        setElementOnColumns(res, column.element)
+        return [res]
+      }
+      return null
+    }
+
+    function flattenForeignKeys() {
+      const flatColumns = []
+      for (const k of element.keys) {
+        const fkElement = getElementForRef(k.ref, getDefinition(element.target))
+        // if only one part of a foreign key is requested, only flatten the partial key
+        const shouldFlatten =
+          !$refLinks || // the association is passed as element, not as ref --> flatten full foreign key
+          element === $refLinks.at(-1).definition || // the association is the leaf of the ref --> flatten full foreign key
+          fkElement === stepAfterAssoc.definition // the foreign key is the leaf of the ref --> only flatten this specific foreign key
+        if (!shouldFlatten) continue
+
+        // e.g. if foreign key is accessed via infix filter - use join alias to access key in target
+        const fkBaseName = !firstNonJoinRelevantAssoc || firstNonJoinRelevantAssoc.onlyForeignKeyAccess
+          ? `${baseName}_${k.as || k.ref.at(-1)}`
+          : k.ref.at(-1)
+        const fkPath = [...csnPath, k.ref.at(-1)]
+
+        if (fkElement.elements) {
+          // structured key
+          for (const e of Object.values(fkElement.elements)) {
+            let alias
+            if (columnAlias) {
+              const fkName = k.as
+                ? `${k.as}_${e.name}` // foreign key might also be re-named: `assoc { id as foo }`
+                : `${k.ref.join('_')}_${e.name}`
+              alias = `${columnAlias}_${fkName}`
+            }
+            flatColumns.push(
+              ...getFlatColumnsFor(
+                e,
+                { baseName: fkBaseName, columnAlias: alias, tableAlias },
+                fkPath,
+                excludeAndReplace,
+                isWildcard,
+              ),
+            )
+          }
+        } else if (fkElement.isAssociation) {
+          // assoc as key
+          flatColumns.push(
+            ...getFlatColumnsFor(fkElement, { baseName, columnAlias, tableAlias }, csnPath, excludeAndReplace, isWildcard),
+          )
+        } else {
+          // leaf reached
+          let flatColumn
+          if (columnAlias) {
+            // if the column has an explicit alias AND the original ref
+            // directly resolves to the foreign key, we must not append the fk name to the column alias
+            // e.g. `assoc.fk as FOO` => columns.alias = FOO
+            //      `assoc as FOO`    => columns.alias = FOO_fk
+            let fkAlias = columnAlias
+            if (!(column.as && fkElement === column.$refLinks?.at(-1).definition))
+              fkAlias = `${columnAlias}_${k.as || k.ref.join('_')}`
+            flatColumn = { ref: [fkBaseName], as: fkAlias }
+          } else {
+            flatColumn = { ref: [fkBaseName] }
+          }
+          if (tableAlias) flatColumn.ref.unshift(tableAlias)
+
+          // in a flat model, we must assign the foreign key rather than the key in the target
+          const flatForeignKey = getDefinition(element.parent.name)?.elements[fkBaseName]
+          setElementOnColumns(flatColumn, flatForeignKey || fkElement)
+          defineProperty(flatColumn, '_csnPath', csnPath)
+          flatColumns.push(flatColumn)
+        }
+      }
+      return flatColumns
+    }
   }
 
   /**
@@ -1726,6 +1736,9 @@ function cqn4sql(originalQuery, model) {
         transformedTokenStream[i + 1] = whereExists
         // skip newly created subquery from being iterated
         i += 1
+      } else if (token !== null && typeof token === 'object' && '#' in token) {
+        // Enum token: resolve to its value
+        transformedTokenStream.push(resolveEnumToken(token, tokenStream, i))
       } else if (token.list) {
         if (token.list.length === 0) {
           // replace `[not] in <empty list>` to harmonize behavior across dbs
@@ -1743,8 +1756,13 @@ function cqn4sql(originalQuery, model) {
             transformedTokenStream.push({ list: [] })
           }
         } else {
-          const { list } = token
-          if (list.every(e => e.val))
+          let { list } = token
+          // Resolve enum tokens in list items using context from the parent token stream
+          if (list.some(e => e !== null && typeof e === 'object' && '#' in e)) {
+            const enumDef = findEnumDefinition(tokenStream, i)
+            list = list.map(item => (item !== null && typeof item === 'object' && '#' in item) ? resolveEnumToken(item, tokenStream, i, enumDef) : item)
+          }
+          if (list.every(e => 'val' in e))
             // no need for transformation
             transformedTokenStream.push({ list })
           else transformedTokenStream.push({ list: getTransformedTokenStream(list, { $baseLink, prop: 'list' }) })
@@ -1776,7 +1794,6 @@ function cqn4sql(originalQuery, model) {
             ops.push(rhs)
             rhs = tokenStream[i + 3]
             indexRhs += 1
-            rhsDef = rhs?.$refLinks?.at(-1)?.definition
           }
 
           if (notSupportedOps.some(([firstOp]) => firstOp === next))
@@ -1846,6 +1863,7 @@ function cqn4sql(originalQuery, model) {
             }
           }
 
+          if (result.cast) result.cast = resolveEnumCastType(result.cast)
           transformedTokenStream.push(result)
         }
       }
@@ -2634,6 +2652,116 @@ function cqn4sql(originalQuery, model) {
     }
     return result
   }
+
+  /**
+   * Resolves an enum token to a value literal.
+   *
+   * If the token already has a `val`, it is used directly.
+   * Otherwise, the enum value is resolved by looking up the symbol
+   * in the enum definition found from the surrounding context.
+   *
+   * @param {object} token - The enum token with a `#` property.
+   * @param {object[]} tokenStream - The surrounding token stream for context discovery.
+   * @param {number} index - The index of the enum token in the token stream.
+   * @param {object} [enumDef] - An already-discovered enum definition (optimization for lists).
+   * @returns {object} A value token `{ val: resolvedValue }`.
+   */
+  function resolveEnumToken(token, tokenStream, index, enumDef) {
+    if ('val' in token) {
+      const result = { val: token.val }
+      if (token.cast) result.cast = resolveEnumCastType(token.cast)
+      return result
+    }
+
+    // Check if the token itself has a cast with an enum type
+    if (!enumDef && token.cast?.type) {
+      const typeDef = model.definitions[token.cast.type]
+      if (typeDef?.enum) enumDef = typeDef.enum
+    }
+
+    if (!enumDef) enumDef = findEnumDefinition(tokenStream, index)
+    if (!enumDef) {
+      throw new Error(`Can't resolve enum value "#${token['#']}"`)
+    }
+
+    const entry = enumDef[token['#']]
+    if (!entry) {
+      throw new Error(`Unknown enum symbol "#${token['#']}"`)
+    }
+
+    const result = { val: 'val' in entry ? entry.val : token['#'] }
+    if (token.cast) result.cast = resolveEnumCastType(token.cast)
+    return result
+  }
+
+  /**
+   * If `cast.type` refers to a user-defined enum type, resolves it to the
+   * underlying scalar CDS built-in type so that the SQL builder (`cqn2sql`)
+   * can render a valid SQL type name.
+   *
+   * Example: `{ type: 'enums.Priority' }` → `{ type: 'cds.Integer' }`
+   *
+   * Non-enum types (including CDS built-ins) are returned unchanged.
+   *
+   * @param {object} cast - The cast descriptor with a `type` property.
+   * @returns {object} The cast descriptor with the resolved type.
+   */
+  function resolveEnumCastType(cast) {
+    if (!cast?.type) return cast
+    let def = model.definitions[cast.type]
+    while (def?.enum) {
+      const baseType = def.type
+      if (!baseType) return cast // no base type declared – leave as-is
+      if (cds.builtin.types[baseType]) return { ...cast, type: baseType }
+      def = model.definitions[baseType]
+    }
+    return cast
+  }
+
+  /**
+   * Scans the token stream around the given index to find an element
+   * definition that has an `enum` property, which can be used to resolve
+   * enum symbols to their values.
+   *
+   * @param {object[]} tokenStream - The token stream to scan.
+   * @param {number} index - The index of the enum token.
+   * @returns {object|null} The enum definition object, or null if not found.
+   */
+  function findEnumDefinition(tokenStream, index) {
+    // Scan backward
+    for (let j = index - 1; j >= 0; j--) {
+      const t = tokenStream[j]
+      if (typeof t === 'string') continue   // operators, keywords
+      if (t !== null && typeof t === 'object' && '#' in t) continue  // other enum tokens
+      if ('val' in t && !t.ref) continue    // plain value literals
+
+      const def = t.$refLinks?.at(-1)?.definition
+      if (def?.enum) return def.enum
+      if (t.cast?.type) {
+        const typeDef = model.definitions[t.cast.type]
+        if (typeDef?.enum) return typeDef.enum
+      }
+      if (def) break  // found a ref without enum type, stop
+    }
+
+    // Scan forward
+    for (let j = index + 1; j < tokenStream.length; j++) {
+      const t = tokenStream[j]
+      if (typeof t === 'string') continue
+      if (t !== null && typeof t === 'object' && '#' in t) continue
+      if ('val' in t && !t.ref) continue
+
+      const def = t.$refLinks?.at(-1)?.definition
+      if (def?.enum) return def.enum
+      if (t.cast?.type) {
+        const typeDef = model.definitions[t.cast.type]
+        if (typeDef?.enum) return typeDef.enum
+      }
+      if (def) break
+    }
+
+    return null
+  }
 }
 
 function calculateElementName(token) {

package/lib/infer/index.js

@@ -11,7 +11,7 @@ const cdsTypes = cds.builtin.types
  * @param {import('@sap/cds/apis/csn').CSN} [model]
  * @returns {import('./cqn').Query} = q with .target and .elements
  */
-function infer(originalQuery, model) {
+function infer(originalQuery, model, useTechnicalAlias = true) {
   if (!model) throw new Error('Please specify a model')
   const inferred = originalQuery
 
@@ -34,7 +34,7 @@ function infer(originalQuery, model) {
 
   let $combinedElements
 
-  const sources = inferTarget(_.into || _.from || _.entity, {}) // IMPORTANT: _.into has to go before _.from for INSERT.into().from(SELECT)
+  const sources = inferTarget(_.into || _.from || _.entity, {}, useTechnicalAlias) // IMPORTANT: _.into has to go before _.from for INSERT.into().from(SELECT)
   const aliases = Object.keys(sources)
   const target = aliases.length === 1 ? getDefinitionFromSources(sources, aliases[0]) : originalQuery
   Object.defineProperties(inferred, {
@@ -80,7 +80,7 @@ function infer(originalQuery, model) {
    *                              Each key is a query source alias, and its value is the corresponding CSN Definition.
    * @returns {object} The updated `querySources` object with inferred sources from the `from` clause.
    */
-  function inferTarget(from, querySources, useTechnicalAlias = true) {
+  function inferTarget(from, querySources, useTechnicalAlias) {
     const { ref } = from
     // Given a from clause `Root:parent[$main.name = name].parent as Foo`
     // we need to first resolve until to the last step of the from.ref

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/db-service",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "CDS base database service",
   "homepage": "https://github.com/cap-js/cds-dbs/tree/main/db-service#cds-base-database-service",
   "repository": {