sql.h

// MIT License
//
// Copyright (c) 2023-2025 Advanced Micro Devices, Inc. All rights reserved.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.

#pragma once

#include <rocprofiler-sdk-rocpd/defines.h>
#include <rocprofiler-sdk-rocpd/types.h>

#include <stdint.h>

ROCPD_EXTERN_C_INIT

/**
 * @defgroup SQL rocPD SQL Utilities
 * @brief Functions for reading rocpd SQL schema
 * @{
 */

/**
 * @brief (experimental) Supported SQL engines. Initial support is for SQLite3, other engines such
 * as MySQL may be added
 */
typedef enum ROCPD_EXPERIMENTAL rocpd_sql_engine_t
{
    ROCPD_SQL_ENGINE_NONE = 0,
    ROCPD_SQL_ENGINE_SQLITE3,  ///< Ensure compatibility with SQLite3
    ROCPD_SQL_ENGINE_LAST,
} rocpd_sql_engine_t;

/**
 * @brief (experimental) Supported SQL schema kinds
 */
typedef enum ROCPD_EXPERIMENTAL rocpd_sql_schema_kind_t
{
    ROCPD_SQL_SCHEMA_NONE = 0,
    ROCPD_SQL_SCHEMA_ROCPD_TABLES,
    ROCPD_SQL_SCHEMA_ROCPD_INDEXES,
    ROCPD_SQL_SCHEMA_ROCPD_VIEWS,
    ROCPD_SQL_SCHEMA_ROCPD_DATA_VIEWS,
    ROCPD_SQL_SCHEMA_ROCPD_SUMMARY_VIEWS,
    ROCPD_SQL_SCHEMA_ROCPD_METADATA,
    ROCPD_SQL_SCHEMA_LAST,
} rocpd_sql_schema_kind_t;

/**
 * @brief (experimental) Supported SQL options
 */
typedef enum ROCPD_EXPERIMENTAL rocpd_sql_options_t
{
    ROCPD_SQL_OPTIONS_NONE                        = 0,
    ROCPD_SQL_OPTIONS_PERSIST_STRINGS             = 0x01,  ///< do not delete strings
    ROCPD_SQL_OPTIONS_SQLITE3_PRAGMA_FOREIGN_KEYS = 0x02,  ///< enable SQLite3 foreign keys
    ROCPD_SQL_OPTIONS_LAST                        = 0xFFFFFFFF,
} rocpd_sql_options_t;

/**
 * @brief (experimental) Schema jinja variable substitution values. In general, the struct member
 * variable replaces jinja variables of the same name, e.g. the struct member variable `uuid`
 * replaces `{{uuid}}` in the schema definition.
 *
 * When the schema variable `{{uuid}}` is a non-null and non-empty string, it
 * will be prefixed with a leading underscore (`_`) and all hyphens will be replaced with
 * underscores. This is because this variable is used in SQL table names. The leading
 * underscore improves the readability of the table name and the replacement of hyphens with
 * underscores is reduces problems.
 */
typedef struct ROCPD_EXPERIMENTAL rocpd_sql_schema_jinja_variables_t
{
    uint64_t    size;  ///< Size of this struct (minus reserved padding)
    const char* uuid;  ///< Substitution for `{{uuid}}` (non-empty adds leading underscore)
    const char* guid;  ///< Substitution for `{{guid}}`
} rocpd_sql_schema_jinja_variables_t;

/**
 * @brief (experimental) Callback providing the schema content after variable substitution.
 *
 * @param [in] engine Schema conforms to this SQL database engine
 * @param [in] kind Schema category
 * @param [in] options Schema options included in content
 * @param [in] variables Jinja variables which were substituted
 * @param [in] schema_path Filesystem path to base schema file
 * @param [in] schema_content SQL schema content is pass to database
 * @param [in] user_data User provided data
 */
ROCPD_EXPERIMENTAL typedef void (*rocpd_sql_load_schema_cb_t)(
    rocpd_sql_engine_t                        engine,
    rocpd_sql_schema_kind_t                   kind,
    rocpd_sql_options_t                       options,
    const rocpd_sql_schema_jinja_variables_t* variables,
    const char*                               schema_path,
    const char*                               schema_content,
    void*                                     user_data);

/**
 * @brief (experimental) Invoke the callback which provides the schema kind definition for the given
 * SQL engine + the addition of the requested options + jinja variable substitution.
 *
 * @param [in] engine SQL schema contents should be compatible with this SQL database engine
 * @param [in] kind SQL schema kind (tables, indexes, views, etc.)
 * @param [in] options Options for the callback and schema
 * @param [in] variables Defines variables for jinja substitution. If nullptr, no jinja variables
 * will be substituted. For each member variable that is a nullptr, jinja for that member variable
 * will not be substituted. To replace jinja variables with empty strings, assign all member
 * variables to empty string.
 * @param [in] callback Callback function which provides the schema contents
 * @param [in] schema_path_hints Suggests for where to find the schema templates
 * @param [in] num_schema_path_hints Number of schema path hints
 * @param [in] user_data Pointer to pass back into callback
 * @return ::rocpd_status_t
 * @retval ROCPD_STATUS_SUCCESS if all parameter specifications were applied and callback
 * successfully invoked
 * @retval ROCPD_STATUS_ERROR_INVALID_ARGUMENT Invalid SQL engine
 * @retval ROCPD_STATUS_ERROR_NOT_AVAILABLE Schema file could not be found
 * @retval ROCPD_STATUS_ERROR_PERMISSION_DENIED Schema file could not be found
 * @retval ROCPD_STATUS_ERROR_KIND_NOT_FOUND Invalid SQL schema kind
 * @retval ROCPD_STATUS_ERROR There was some issue with parameters
 * @retval ROCPD_STATUS_ERROR_INVALID_ARGUMENT ::rocpd_sql_schema_jinja_variables_t size parameter
 * not set
 */
ROCPD_EXPERIMENTAL rocpd_status_t
rocpd_sql_load_schema(rocpd_sql_engine_t                        engine,
                      rocpd_sql_schema_kind_t                   kind,
                      rocpd_sql_options_t                       options,
                      const rocpd_sql_schema_jinja_variables_t* variables,
                      rocpd_sql_load_schema_cb_t                callback,
                      const char**                              schema_path_hints,
                      uint64_t                                  num_schema_path_hints,
                      void* user_data) ROCPD_API ROCPD_NONNULL(5);

/** @} */

ROCPD_EXTERN_C_FINI