feat: Add C ABI for embedded seekdb (multi‑language SDKs) by dengfuping · Pull Request #135 · oceanbase/seekdb

dengfuping · 2026-01-28T03:44:21Z

Task Description

Fix [Feature]: Stable C ABI for embedded seekdb (multi‑language SDKs) #104.

Solution Description

Architecture Design:

Language Bindings (Node.js, Python, Rust, Go)
           │
           ▼
    SeekDB C ABI (seekdb.h/seekdb.cpp)
           │
           ▼
    OceanBase Core (liboceanbase.so)

Source Code Directory (src/include/)

src/include/
├── seekdb.h                          # Public C API header file
│                                     # - All function declarations
│                                     # - Type definitions (SeekdbHandle, SeekdbResult, etc.)
│                                     # - Data structures (SeekdbBind, SeekdbField)
│                                     # - MySQL C API compatible interface
│
├── seekdb.cpp                        # C ABI implementation (~4800 lines)
│                                     # - Global initialization (seekdb_open/close)
│                                     # - Connection management
│                                     # - Query execution & Result set operations
│                                     # - Prepared Statement API
│                                     # - Signal handling & Stack management
│
├── CMakeLists.txt                    # Build configuration for libseekdb.so

Test Directory (`unittest/include/`)

unittest/include/
├── test_seekdb.cpp                   # C++ unit test suite (comprehensive)
│                                     # - Tests all C API functions directly
│                                     # - Complete API coverage
│
├── nodejs/                           # Node.js FFI binding (koffi)
│   ├── seekdb.js                    # FFI wrapper
│   ├── test.js                      # Test suite
│   └── test.sh                      # Test execution script
│
├── nodejs_napi/                      # Node.js N-API binding (native addon)
│   ├── seekdb.cpp                   # N-API C++ implementation
│   ├── test.js                      # Test suite
│   └── test.sh                      # Test execution script
│
├── python/                           # Python binding (ctypes)
│   ├── seekdb.py                    # FFI wrapper
│   ├── test.py                      # Test suite
│   └── test.sh                      # Test execution script
│
├── rust/                             # Rust FFI binding
│   ├── src/
│   │   ├── lib.rs                   # FFI bindings
│   │   └── test.rs                  # Test suite
│   └── test.sh                      # Test execution script
│
└── go/                               # Go binding (cgo)
    ├── seekdb/seekdb.go              # FFI wrapper
    ├── test.go                       # Test suite
    └── test.sh                       # Test execution script

Passed Regressions

Build and test:

# build libseekdb library
./build.sh release --init -DBUILD_EMBED_MODE=ON --make

# unittest
make -j$(nproc) test_seekdb
cd build_release/unittest/include && ./test_seekdb

# bindings test
cd unittest/include/nodejs && bash ./test.sh
cd unittest/include/nodejs_napi && bash ./test.sh
cd unittest/include/python && bash ./test.sh
cd unittest/include/go && bash ./test.sh
cd unittest/include/rust && bash ./test.sh

Upgrade Compatibility

Compatible

Other Information

seekdb-js integration:
seekdb-rs integration (WIP)

Release Note

🆕 Add C ABI for embedded seekdb (multi‑language SDKs).

dengfuping · 2026-01-28T03:46:05Z

SeekDB C ABI vs MySQL 5.7 C API Complete Comparison

Document Information

Reference Document: MySQL 5.7 C API Function Reference

Alignment Status Overview

Category	Implemented	Unimplemented	Partially Implemented	Alignment
Basic Functions	3	3	0	50%
Connection Management	7	7	0	50%
Query Execution	6	0	0	100%
Result Set Operations	17	1	0	94%
Error Handling	3	0	0	100%
Character Set	3	0	0	100%
Transactions	3	0	0	100%
Information Queries	4	6	0	40%
Utility Functions	3	2	0	60%
Database Management	0	10	0	0%
Prepared Statement API	25	2	1	93%
Thread API	0	4	0	0%
Plugin API	0	5	0	0%
Total	75	39	1	~64%

Core Function Alignment: 100% ✅ (Parameterized queries, column name retrieval, error handling, character set, transactions)

Notes:

Basic Functions: Includes initialization functions like mysql_init(), mysql_library_init()
Connection Management: Includes connection, close, option setting functions
Query Execution: Includes mysql_query(), mysql_affected_rows(), etc.
Result Set Operations: Includes mysql_store_result(), mysql_fetch_*(), etc. (core functionality for column name retrieval)
Prepared Statement API: Core functionality for parameterized queries
Database Management: Deprecated functions or functions that can be replaced by SQL

Complete MySQL C API Function List (in official documentation order)

Basic Functions

MySQL C API	SeekDB C API	Status	Description	Deprecated
`my_init()`	❌	❌	Initialize client library global variables
`mysql_init()`	`seekdb_connect()`	✅	Get or initialize MYSQL structure (embedded mode)
`mysql_library_init()`	`seekdb_open()`	✅	Initialize MySQL C API library (SeekDB uses `seekdb_open()`)
`mysql_library_end()`	`seekdb_close()`	✅	End MySQL C API library (SeekDB uses `seekdb_close()`)
`mysql_server_init()`	❌	❌	Deprecated, SeekDB uses `seekdb_open()`	Yes
`mysql_server_end()`	❌	❌	Deprecated, SeekDB uses `seekdb_close()`	Yes

Connection Management

MySQL C API	SeekDB C API	Status	Description	Deprecated
`mysql_real_connect()`	`seekdb_connect()`	✅	Connect to MySQL server (embedded mode)
`mysql_connect()`	❌	❌	Connect to MySQL server	Yes
`mysql_close()`	`seekdb_connect_close()`	✅	Close connection to server
`mysql_ping()`	`seekdb_ping()`	✅	Ping server
`mysql_select_db()`	`seekdb_select_db()`	✅	Select database
`mysql_change_user()`	`seekdb_change_user()`	✅	Change user and database
`mysql_reset_connection()`	`seekdb_reset_connection()`	✅	Reset connection to clear session state
`mysql_options()`	❌	❌	Set options before connection (not needed in embedded mode)
`mysql_options4()`	❌	❌	Set options before connection (not needed in embedded mode)
`mysql_get_option()`	❌	❌	Get value of `mysql_options()` option
`mysql_ssl_set()`	❌	❌	Prepare SSL connection to server (not needed in embedded mode)
`mysql_get_ssl_cipher()`	❌	❌	Current SSL cipher (not needed in embedded mode)
`mysql_set_server_option()`	❌	❌	Set option for current connection
`mysql_set_local_infile_handler()`	❌	❌	Install application-specific LOAD DATA LOCAL handler callback
`mysql_set_local_infile_default()`	❌	❌	Set LOAD DATA LOCAL handler callback to default

Query Execution

MySQL C API	SeekDB C API	Status	Description
`mysql_query()`	`seekdb_query()`	✅	Execute statement
`mysql_real_query()`	`seekdb_real_query()`	✅	Execute statement (binary-safe)
`mysql_affected_rows()`	`seekdb_affected_rows()`	✅	Number of rows changed/deleted/inserted by last UPDATE/DELETE/INSERT statement
`mysql_insert_id()`	`seekdb_insert_id()`	✅	ID generated for AUTO_INCREMENT column by last statement
`mysql_info()`	`seekdb_info()`	✅	Information about most recently executed statement
`mysql_warning_count()`	`seekdb_warning_count()`	✅	Warning count for last statement

Result Set Operations

MySQL C API	SeekDB C API	Status	Description	Deprecated
`mysql_store_result()`	`seekdb_store_result()`	✅	Retrieve and store entire result set
`mysql_use_result()`	`seekdb_use_result()`	✅	Initiate row-by-row result set retrieval
`mysql_free_result()`	`seekdb_result_free()`	✅	Free result set memory
`mysql_num_fields()`	`seekdb_num_fields()`	✅	Number of columns in result set
`mysql_num_rows()`	`seekdb_num_rows()`	✅	Number of rows in result set
`mysql_field_count()`	`seekdb_field_count()`	✅	Number of result columns for most recent statement
`mysql_fetch_row()`	`seekdb_fetch_row()`	✅	Get next result set row
`mysql_fetch_lengths()`	`seekdb_fetch_lengths()`	✅	Return lengths of all columns in current row
`mysql_fetch_fields()`	`seekdb_fetch_fields()`	✅	Return array of all field structures
`mysql_fetch_field()`	`seekdb_fetch_field()`	✅	Type of next table field
`mysql_fetch_field_direct()`	`seekdb_fetch_field_direct()`	✅	Type of table field for given field number
`mysql_field_seek()`	`seekdb_field_seek()`	✅	Position to column in result set row
`mysql_field_tell()`	`seekdb_field_tell()`	✅	Field position of last `mysql_fetch_field()` call
`mysql_data_seek()`	`seekdb_data_seek()`	✅	Position to arbitrary row number in query result set
`mysql_row_seek()`	`seekdb_row_seek()`	✅	Position to row offset in result set
`mysql_row_tell()`	`seekdb_row_tell()`	✅	Current position within result set row
`mysql_eof()`	❌	❌	Determine whether last row of result set has been read	Yes
`mysql_more_results()`	`seekdb_more_results()`	✅	Check whether more results exist
`mysql_next_result()`	`seekdb_next_result()`	✅	Return/initiate next result in multiple-result execution

Error Handling

MySQL C API	SeekDB C API	Status	Description
`mysql_errno()`	`seekdb_errno()`	✅	Error number for most recently invoked MySQL function
`mysql_error()`	`seekdb_error()`	✅	Error message for most recently invoked MySQL function
`mysql_sqlstate()`	`seekdb_sqlstate()`	✅	SQLSTATE value for most recently invoked MySQL function

Character Set

MySQL C API	SeekDB C API	Status	Description
`mysql_character_set_name()`	`seekdb_character_set_name()`	✅	Default character set name for current connection
`mysql_set_character_set()`	`seekdb_set_character_set()`	✅	Set default character set for current connection
`mysql_get_character_set_info()`	`seekdb_get_character_set_info()`	✅	Information about default character set

Transactions

MySQL C API	SeekDB C API	Status	Description
`mysql_autocommit()`	`seekdb_autocommit()`	✅	Set autocommit mode
`mysql_commit()`	`seekdb_commit()`	✅	Commit transaction
`mysql_rollback()`	`seekdb_rollback()`	✅	Roll back transaction
`seekdb_begin()`	✅	✅	Begin transaction (SeekDB extension, MySQL uses `START TRANSACTION`)

Information Queries

MySQL C API	SeekDB C API	Status	Description
`mysql_get_server_info()`	`seekdb_get_server_info()`	✅	Server version number (string)
`mysql_get_server_version()`	`seekdb_get_server_version()`	✅	Server version number (integer)
`mysql_get_client_info()`	`seekdb_get_client_info()`	✅	Client version (string)
`mysql_get_client_version()`	❌	❌	Client version (integer)
`mysql_get_host_info()`	`seekdb_get_host_info()`	✅	Information about connection
`mysql_get_proto_info()`	❌	❌	Protocol version used by connection (not needed in embedded mode)
`mysql_thread_id()`	❌	❌	Current thread ID (not needed in embedded mode)
`mysql_stat()`	❌	❌	Server status (can be queried via SQL)
`mysql_dump_debug_info()`	❌	❌	Cause server to write debug information to error log (not needed in embedded mode)
`mysql_session_track_get_first()`	❌	❌	First part of session state change information
`mysql_session_track_get_next()`	❌	❌	Next part of session state change information

Utility Functions

MySQL C API	SeekDB C API	Status	Description
`mysql_real_escape_string()`	`seekdb_real_escape_string()`	✅	Encode special characters in statement string
`mysql_real_escape_string_quote()`	`seekdb_real_escape_string_quote()`	✅	Encode special characters in statement string (considering quote context, MySQL 8.0+)
`mysql_escape_string()`	❌	❌	Escape special characters in string for use in SQL statement
`mysql_hex_string()`	`seekdb_hex_string()`	✅	Encode string in hexadecimal format
`mysql_debug()`	❌	❌	Execute DBUG_PUSH with given string (not needed in embedded mode)

Database Management (Deprecated or Replaceable by SQL)

MySQL C API	SeekDB C API	Status	Description	Deprecated
`mysql_create_db()`	❌	❌	Create database	Yes
`mysql_drop_db()`	❌	❌	Drop database	Yes
`mysql_list_dbs()`	❌	❌	Return database names matching regex (can be queried via SQL)
`mysql_list_tables()`	❌	❌	Return table names matching regex (can be queried via SQL)
`mysql_list_fields()`	❌	❌	Return field names matching regex	5.7.11
`mysql_list_processes()`	❌	❌	Current server thread list	5.7.11
`mysql_kill()`	❌	❌	Kill thread	Yes
`mysql_reload()`	❌	❌	Reload grant tables	Yes
`mysql_refresh()`	❌	❌	Refresh or reset tables and caches	5.7.11
`mysql_shutdown()`	❌	❌	Shut down MySQL server	Yes

Prepared Statement API (Parameterized Queries)

Core API

MySQL C API	SeekDB C API	Status	Description
`mysql_stmt_init()`	`seekdb_stmt_init()`	✅	Allocate and initialize memory for MYSQL_STMT structure
`mysql_stmt_prepare()`	`seekdb_stmt_prepare()`	✅	Prepare statement for execution
`mysql_stmt_bind_param()`	`seekdb_stmt_bind_param()`	✅	Associate application data buffers with parameter markers in prepared statement
`mysql_stmt_execute()`	`seekdb_stmt_execute()`	✅	Execute prepared statement
`mysql_stmt_bind_result()`	`seekdb_stmt_bind_result()`	✅	Associate application data buffers with columns in result set
`mysql_stmt_fetch()`	`seekdb_stmt_fetch()`	✅	Fetch next result set row and return data for all bound columns
`mysql_stmt_result_metadata()`	`seekdb_stmt_result_metadata()`	✅	Return prepared statement metadata as result set
`mysql_stmt_close()`	`seekdb_stmt_close()`	✅	Free memory used by prepared statement

Enhanced API

MySQL C API	SeekDB C API	Status	Description
`mysql_stmt_param_count()`	`seekdb_stmt_param_count()`	✅	Number of parameters in prepared statement
`mysql_stmt_affected_rows()`	`seekdb_stmt_affected_rows()`	✅	Number of rows changed/deleted/inserted by last prepared UPDATE/DELETE/INSERT statement
`mysql_stmt_insert_id()`	`seekdb_stmt_insert_id()`	✅	ID generated for AUTO_INCREMENT column by last prepared statement
`mysql_stmt_num_rows()`	`seekdb_stmt_num_rows()`	✅	Number of rows in buffered statement result set
`mysql_stmt_free_result()`	`seekdb_stmt_free_result()`	✅	Free resources allocated to statement handler
`mysql_stmt_error()`	`seekdb_stmt_error()`	✅	Error message for most recently invoked MySQL prepared statement function
`mysql_stmt_errno()`	`seekdb_stmt_errno()`	✅	Error number for most recently invoked MySQL prepared statement function
`mysql_stmt_sqlstate()`	`seekdb_stmt_sqlstate()`	✅	SQLSTATE value for most recently invoked MySQL prepared statement function
`mysql_stmt_reset()`	`seekdb_stmt_reset()`	✅	Reset server-side statement buffer
`mysql_stmt_data_seek()`	`seekdb_stmt_data_seek()`	✅	Position to arbitrary row number in prepared statement result set
`mysql_stmt_row_seek()`	`seekdb_stmt_row_seek()`	✅	Position to row offset in prepared statement result set
`mysql_stmt_row_tell()`	`seekdb_stmt_row_tell()`	✅	Current position within prepared statement result set row
`mysql_stmt_field_count()`	`seekdb_stmt_field_count()`	✅	Number of result columns for most recent prepared statement
`mysql_stmt_fetch_column()`	`seekdb_stmt_fetch_column()`	✅	Fetch data for one column of current result set row
`mysql_stmt_param_metadata()`	`seekdb_stmt_param_metadata()`	✅	Return parameter metadata as result set
`mysql_stmt_next_result()`	`seekdb_stmt_next_result()`	⚠️	Return/initiate next result in multiple-result prepared statement execution (returns -1, not yet supported)
`mysql_stmt_store_result()`	`seekdb_stmt_store_result()`	✅	Retrieve and store entire result set
`mysql_stmt_send_long_data()`	❌	❌	Send long data to server in chunks (BLOB streaming, advanced feature)
`mysql_stmt_attr_get()`	❌	❌	Get attribute value for prepared statement (advanced configuration)
`mysql_stmt_attr_set()`	❌	❌	Set attribute value for prepared statement (advanced configuration)

Alignment: 25/26 = 96% ✅

Thread API (Not needed in embedded mode)

MySQL C API	SeekDB C API	Status	Description
`mysql_thread_init()`	❌	❌	Initialize thread handler
`mysql_thread_end()`	❌	❌	End thread handler
`mysql_thread_safe()`	❌	❌	Whether client is compiled thread-safe
`my_init()`	❌	❌	Initialize client library global variables

Plugin API (Not needed in embedded mode)

MySQL C API	SeekDB C API	Status	Description
`mysql_client_register_plugin()`	❌	❌	Register plugin
`mysql_client_find_plugin()`	❌	❌	Return pointer to plugin
`mysql_load_plugin()`	❌	❌	Load plugin
`mysql_load_plugin_v()`	❌	❌	Load plugin (with version)
`mysql_plugin_options()`	❌	❌	Set plugin options

SeekDB Extended API (Additional convenience functions)

SeekDB C API	Description	MySQL Equivalent
`seekdb_open()`	Open embedded database	None (SeekDB specific)
`seekdb_open_with_service()`	Open database (with service mode support)	None (SeekDB specific)
`seekdb_close()`	Close embedded database	None (SeekDB specific)
`seekdb_query_with_params()`	Query with parameters (convenience function)	None (uses Prepared Statement internally)
`seekdb_real_query_with_params()`	Query with parameters (binary-safe)	None (uses Prepared Statement internally)
`seekdb_result_get_all_column_names()`	Get all column names in batch (pre-allocated buffer)	None (convenience function)
`seekdb_result_get_all_column_names_alloc()`	Get all column names in batch (auto-allocated)	None (convenience function)
`seekdb_free_column_names()`	Free column name memory	None (convenience function)
`seekdb_result_fetch_all()`	Fetch all rows using callback	None (convenience function)
`seekdb_result_fetch_all_rows()`	Fetch all rows (array form)	None (convenience function)
`seekdb_result_free_all_rows()`	Free all row memory	None (convenience function)
`seekdb_row_get_string()`	Get string value	None (type-safe access)
`seekdb_row_get_int64()`	Get integer value	None (type-safe access)
`seekdb_row_get_double()`	Get floating-point value	None (type-safe access)
`seekdb_row_get_bool()`	Get boolean value	None (type-safe access)
`seekdb_row_is_null()`	Check if NULL	None (type-safe access)
`seekdb_row_get_string_len()`	Get string length	None (type-safe access)
`seekdb_begin()`	Begin transaction	None (convenience function, MySQL uses `START TRANSACTION`)
`seekdb_get_last_error()`	Get last error (with buffer)	None (convenience function)
`seekdb_last_error()`	Get last error (thread-local)	None (convenience function)
`seekdb_last_error_code()`	Get last error code (thread-local)	None (convenience function)

Data Structure Alignment

SeekdbBind ↔ MYSQL_BIND (100% aligned)

MySQL Field	SeekDB Field	Type	Alignment Status
`enum_field_types buffer_type`	`SeekdbFieldType buffer_type`	enum	✅
`void* buffer`	`void* buffer`	void*	✅
`unsigned long buffer_length`	`unsigned long buffer_length`	unsigned long	✅
`unsigned long* length`	`unsigned long* length`	unsigned long*	✅
`my_bool* is_null`	`bool* is_null`	bool*	✅
`my_bool* error`	`bool* error`	bool*	✅
`unsigned char* is_unsigned`	`unsigned char* is_unsigned`	unsigned char*	✅

SeekdbField ↔ MYSQL_FIELD (100% aligned)

MySQL Field	SeekDB Field	Type	Alignment Status
`char* name`	`const char* name`	char*	✅
`char* org_name`	`const char* org_name`	char*	✅
`char* table`	`const char* table`	char*	✅
`char* org_table`	`const char* org_table`	char*	✅
`char* db`	`const char* db`	char*	✅
`char* catalog`	`const char* catalog`	char*	✅
`char* def`	`const char* def`	char*	✅
`unsigned long length`	`uint32_t length`	unsigned long/uint32_t	✅
`unsigned long max_length`	`uint32_t max_length`	unsigned long/uint32_t	✅
`unsigned int name_length`	`uint32_t name_length`	unsigned int/uint32_t	✅
`unsigned int org_name_length`	`uint32_t org_name_length`	unsigned int/uint32_t	✅
`unsigned int table_length`	`uint32_t table_length`	unsigned int/uint32_t	✅
`unsigned int org_table_length`	`uint32_t org_table_length`	unsigned int/uint32_t	✅
`unsigned int db_length`	`uint32_t db_length`	unsigned int/uint32_t	✅
`unsigned int catalog_length`	`uint32_t catalog_length`	unsigned int/uint32_t	✅
`unsigned int def_length`	`uint32_t def_length`	unsigned int/uint32_t	✅
`unsigned int flags`	`uint32_t flags`	unsigned int/uint32_t	✅
`unsigned int decimals`	`uint32_t decimals`	unsigned int/uint32_t	✅
`unsigned int charsetnr`	`uint32_t charsetnr`	unsigned int/uint32_t	✅
`enum enum_field_types type`	`int32_t type`	enum/int32_t	✅
`void* extension`	`void* extension`	void*	✅

SeekdbFieldType ↔ enum_field_types (100% aligned)

All field type enumeration values are fully aligned.

Alignment Summary

Core Function Alignment: 100% ✅

The following core functions are fully aligned:

Prepared Statement API (Parameterized queries): 92% ✅
Result Set API (Column name retrieval): 100% ✅
Error Handling API (Error handling): 100% ✅
Character Set API (Character set): 100% ✅
Transaction API (Transactions): 100% ✅
Data Structures: 100% ✅

Overall Alignment: ~64%

Considering that SeekDB is an embedded database, many functions in MySQL C API related to network connections, server management, and plugins are not applicable:

Implemented: 75 functions
Unimplemented: 39 functions (most of which are not needed in embedded mode)
Partially Implemented: 1 function (seekdb_stmt_next_result())
SeekDB Extensions: 20+ convenience functions

Practical Usable Alignment: ~96%

If only considering functions actually needed in embedded database scenarios:

Core Functions: 100% ✅ (Parameterized queries, column name retrieval, error handling, character set, transactions)
Enhanced Functions: ~96% ✅ (Prepared Statement API 96%)
Overall Alignment: ~96% ✅

Implemented Medium Priority APIs: 4 ✅ (2026-01-27)

✅ seekdb_real_escape_string_quote() - String escaping (considering quote context)
✅ seekdb_stmt_param_metadata() - Parameter metadata
✅ seekdb_stmt_store_result() - Store Prepared Statement result set
✅ seekdb_reset_connection() - Reset connection state

Unimplemented API Evaluation and Recommendations

Evaluation Principles

Embedded Mode Applicability: SeekDB is an embedded database, network connections, server management, etc. are not applicable
Actual Use Cases: Evaluate actual requirements in AI Native database and RAG/Agent applications
MySQL Compatibility: Evaluate impact on MySQL C API compatibility
Implementation Complexity: Evaluate implementation and maintenance costs
Alternative Solutions: Evaluate if there are alternatives (e.g., via SQL)

Priority Classification

🔴 High Priority (Recommended to implement)

None

🟡 Medium Priority (Recommended to implement)

~~1. seekdb_real_escape_string_quote() - String escaping (considering quote context)~~ ✅ Implemented (2026-01-27)
~~2. seekdb_stmt_param_metadata() - Complete parameter metadata~~ ✅ Implemented (2026-01-27)
~~3. seekdb_stmt_store_result() - Store Prepared Statement result set~~ ✅ Implemented (2026-01-27)
~~4. seekdb_reset_connection() - Reset connection state~~ ✅ Implemented (2026-01-27)

🟢 Low Priority (Optional implementation)

seekdb_get_client_version() - Client version number (integer format, string version already exists)
seekdb_escape_string() - String escaping (no connection handle, deprecated but for compatibility)
seekdb_stmt_next_result() - Multiple result set support (stored procedures, currently returns -1)

⚪ Not Needed

All network connection related APIs (SSL, option settings, etc.) - Not needed in embedded mode
All server management related APIs (threads, processes, shutdown, etc.) - Not needed in embedded mode
All plugin system APIs - Not needed in embedded mode
All thread management APIs - Not needed in embedded mode
All deprecated database management APIs (can be replaced by SQL)
All debugging related APIs - Not needed in embedded mode
mysql_eof() - Deprecated (MySQL 5.7.11+), use seekdb_fetch_row() returning NULL to determine

Implementation Recommendations

Short-term (1-2 iterations): ✅ Completed (2026-01-27)
- ~~Complete seekdb_stmt_param_metadata() implementation~~ ✅
- ~~Implement seekdb_reset_connection()~~ ✅
Medium-term (3-6 iterations): ✅ Completed (2026-01-27)
- ~~Implement seekdb_real_escape_string_quote()~~ ✅
- ~~Implement seekdb_stmt_store_result()~~ ✅
Long-term (as needed):
- Implement seekdb_get_client_version() (simple wrapper)
- Implement seekdb_escape_string() (for compatibility)
- Complete seekdb_stmt_next_result() (stored procedure support)

Key Unimplemented API Notes

MySQL C API	Status	Evaluation Conclusion	Description
`mysql_get_client_version()`	❌	🟢 Low Priority	String version `seekdb_get_client_info()` already exists
`mysql_escape_string()`	❌	🟢 Low Priority	Deprecated, but can be provided for compatibility
`mysql_get_proto_info()`	❌	⚪ Not Needed	No network protocol in embedded mode
`mysql_thread_id()`	❌	⚪ Not Needed	No server-side thread concept in embedded mode
`mysql_stat()`	❌	⚪ Not Needed	Can be queried via SQL `SHOW STATUS`
`mysql_eof()`	❌	⚪ Not Needed	Deprecated (MySQL 5.7.11+)
`mysql_stmt_next_result()`	⚠️	🟢 Low Priority	Partially implemented (returns -1), stored procedure support
`mysql_stmt_send_long_data()`	❌	⚪ Not Needed	Advanced feature, limited use cases
`mysql_options()` series	❌	⚪ Not Needed	Connection options not needed in embedded mode
`mysql_ssl_*()` series	❌	⚪ Not Needed	SSL not needed in embedded mode
`mysql_debug()`	❌	⚪ Not Needed	Debugging feature, not applicable in embedded mode

Usage Recommendations

1. Code Migration

Migrating from MySQL C API to SeekDB C API:

Replace function names: mysql_* → seekdb_*
Replace type names: MYSQL_* → Seekdb*
Replace constants: MYSQL_TYPE_* → SEEKDB_TYPE_*
Connection method: Use seekdb_open() and seekdb_connect() instead of mysql_init() and mysql_real_connect()

2. Function Mapping

MySQL Functionality	SeekDB Equivalent
`mysql_init()` + `mysql_real_connect()`	`seekdb_open()` + `seekdb_connect()`
`mysql_close()`	`seekdb_connect_close()`
`mysql_query()`	`seekdb_query()`
`mysql_stmt_*`	`seekdb_stmt_*`
`mysql_fetch_*`	`seekdb_fetch_*`

3. Best Practices

✅ Use Prepared Statement for parameterized queries
✅ Use seekdb_fetch_fields() to get complete field information
✅ Use seekdb_real_escape_string() to escape strings
✅ Use transaction APIs to manage data consistency

Conclusion

SeekDB C ABI is fully aligned (100%) with MySQL 5.7 C API in core functions, and achieves high alignment (~96%) in practically usable functions.

This makes SeekDB a viable embedded alternative to MySQL C API, providing the same development experience while supporting embedded database mode.

Current Status Summary

Core Function Alignment: 100% ✅
Practical Usable Alignment: ~96% ✅
Prepared Statement API Alignment: 96% ✅
Implemented Medium Priority APIs: 4 ✅ (2026-01-27)

Unimplemented Functions

Not Needed (~40 APIs):

Network connection related (SSL, option settings, etc.) - Not needed in embedded mode
Server management related (threads, processes, shutdown, etc.) - Not needed in embedded mode
Plugin system - Not needed in embedded mode
Thread management - Not needed in embedded mode
Deprecated database management APIs (can be replaced by SQL)

Optional Implementation (Low priority, 3 APIs):

seekdb_get_client_version() - Client version number (integer format)
seekdb_escape_string() - String escaping (for compatibility)
seekdb_stmt_next_result() - Multiple result set support (stored procedures)

These functions do not affect basic database operations, parameterized queries, and column name retrieval. All 4 medium priority APIs have been implemented, improving Prepared Statement completeness and connection management capabilities.

…ith MySQL C API

…st scripts for darwin

…sult set

…. [1.1, 2.2, 3.3])

…dout to log file before set_file_name

…ix MTL_SWITCH namespace; remove §7/doc refs - C ABI: row_nulls for NULL vs empty; read_lob_data for TEXT/JSON LOB; MTL_SWITCH(OB_SYS_TENANT_ID) for ObLobManager; namespace share alias for MTL_SWITCH - test: 100KB LONGTEXT via SET SESSION ob_default_lob_inrow_threshold=262144, no table option; special chars metadata test; remove §7 and c-abi-modification-reference references from comments and error messages

- Add LOB read paths for TEXT/JSON columns in result row serialization - Use print_sql_literal for ObJsonType cells and expand buffer to 32KB - Add col_is_metadata heuristic: write "{}" for empty metadata in fallback paths - Add unit tests: very long document (100KB), special chars in metadata, empty JSON metadata

…mpat, install GTest on macOS

…docs

…us ownership

…make explicitly

… OB_CCACHE in workflow

- macOS: put ccache in deps devtools/bin so Env.cmake finds it without code change - Linux: install base deps (incl. wget) first so dep_create.sh can download RPMs - Linux: try EPEL+ccache; use OB_USE_CCACHE=OFF when ccache not available in container

…o feat/embedded-mode

…tra subdir

…est_seekdb_absolute, remove in-process close+open test

…o feat/embedded-mode

…ibc-header-start.h error

…II redirect before CALL_WITH_NEW_STACK

…o feat/embedded-mode

…lities

…le change Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

…ed-mode

…Range> for macOS arm64 link

…SEGV handler in seekdb_close

…, and cert import script

…anches and upload S3 only on main/master/develop/integration/*.*.x

…named-value 'env'

…onsistency

…tu build

…ed-mode

dengfuping force-pushed the feat/embedded-mode branch 2 times, most recently from 9263830 to 0a07b97 Compare January 28, 2026 05:24

dengfuping mentioned this pull request Jan 30, 2026

feat: Integrate libseekdb to support embedded mode oceanbase/seekdb-js#7

Merged

4 tasks

dengfuping force-pushed the feat/embedded-mode branch from 9077a16 to 62d3ef8 Compare January 30, 2026 10:52

dengfuping added 23 commits January 30, 2026 18:55

feat: Add C ABI for embedded seekdb (multi‑language SDKs)

ce1b6df

refactor(seekdb): remove seekdb_row_free API and align row lifetime w…

01a9b14

…ith MySQL C API

fix(build): only create the seekdb library in BUILD_EMBED_MODE

3a47572

improve(include): libseekdb support macos build

19cf0ec

fix(build): specify DPYTHON_VERSION to build libseekdb

4b8ca2f

fix(ci): make seekdb => make libseekdb

d80c2fc

fix(ci): build cache should work

bbfd6ac

improve(include): generate macOS export list from seekdb.h and fix te…

58be1aa

…st scripts for darwin

fix(embed): VARBINARY_ID param binding and fix parameterized query re…

5e5ea84

…sult set

fix(embed): return VECTOR column as JSON string without rounding (e.g…

74feed2

…. [1.1, 2.2, 3.3])

improve(ci): use build_debug for libseekdb

ac57a17

fix(include): remove unimplemented API declarations from seekdb.h

68f3c2f

fix(embed): suppress "successfully init log writer" by redirecting st…

a4f8d52

…dout to log file before set_file_name

feat(package): add libseekdb build script and zip packaging

dca48a3

feat(ci): Add build-libseekdb.yml

7a53af1

ci(libseekdb): multi-platform build, S3 upload, CentOS 7/macOS 11+ co…

1bd1cb2

…mpat, install GTest on macOS

ci(libseekdb): switch macOS runner from macos-13 to macos-14, update …

fee1009

…docs

ci(libseekdb): add git safe.directory in Linux container to fix dubio…

985a640

…us ownership

ci(libseekdb): fix make receiving -D options by dropping --make, run …

dae2642

…make explicitly

ci(libseekdb): add ccache cache for Linux and macOS builds

dc93cb6

ci(libseekdb): detect runner Python first, install if not usable; set…

d4223c6

… OB_CCACHE in workflow

dengfuping force-pushed the feat/embedded-mode branch from 62d3ef8 to d4223c6 Compare January 30, 2026 10:57

Merge branch 'feat/embedded-mode' of github.com:dengfuping/seekdb int…

ca0b4cd

…o feat/embedded-mode

dengfuping mentioned this pull request Feb 4, 2026

feat: Add C ABI for embedded seekdb (multi‑language SDKs) #153

Closed

dengfuping and others added 16 commits February 4, 2026 14:28

ci(libseekdb): use merge-multiple for artifacts, upload S3 without ex…

dc7cc9a

…tra subdir

test(bindings): run full suite with absolute path (second run), add t…

6dd301a

…est_seekdb_absolute, remove in-process close+open test

Merge branch 'feat/embedded-mode' of github.com:dengfuping/seekdb int…

d6172a9

…o feat/embedded-mode

ci(libseekdb): fix cache keys for deps/ccache so second run hits

f76b250

package(libseekdb): improve macOS dylib bundle and @loader_path restore

c067fdd

Merge branch 'feat/embedded-mode' of github.com:dengfuping/seekdb int…

079c2cb

…o feat/embedded-mode

ci(buildbase): use system compiler for node-gyp N-API to avoid bits/l…

eff01a9

…ibc-header-start.h error

fix(embed): suppress LOG_STDOUT (successfully init log writer) via RA…

a503822

…II redirect before CALL_WITH_NEW_STACK

Merge branch 'feat/embedded-mode' of github.com:dengfuping/seekdb int…

8cb64ff

…o feat/embedded-mode

fix(nodejs_napi): npm audit fix for brace-expansion and tar vulnerabi…

71aa7ed

…lities

fix(ci): use actual built commit sha for libseekdb run-name and S3 paths

e876e7f

improve(ci): libseekdb workflow manual run and trigger on workflow fi…

2e91bc6

…le change Co-authored-by: Cursor <cursoragent@cursor.com>

Merge branch, resolve zlib_lite deletion conflict

b6d6fed

Co-authored-by: Cursor <cursoragent@cursor.com>

Merge branch 'master' of github.com:oceanbase/seekdb into feat/embedd…

862e027

…ed-mode

Merge branch 'master' of github.com:oceanbase/seekdb into feat/embedd…

7fc68ae

…ed-mode

fix(storage): add explicit instantiation of build_range_array<ObStore…

af84c4b

…Range> for macOS arm64 link

dengfuping force-pushed the feat/embedded-mode branch from dfe593e to af84c4b Compare February 24, 2026 07:23

dengfuping added 2 commits February 25, 2026 18:37

fix(embed): recognize cleanup segfaults after close and reinstall SIG…

d6cb94b

…SEGV handler in seekdb_close

ci(libseekdb): add macOS code signing with Developer ID, entitlements…

ea10c8b

…, and cert import script

dengfuping mentioned this pull request Feb 26, 2026

feat: Integrate libseekdb to support embedded mode ob-labs/seekdb-rs#4

Open

dengfuping added 5 commits February 27, 2026 14:31

ci(libseekdb): run binding tests in each build job, trigger on all br…

ea9e274

…anches and upload S3 only on main/master/develop/integration/*.*.x

ci(buildbase): restore debug-only build and remove ccache restore-keys

9169c43

fix(ci): avoid env context in workflow top-level to fix Unrecognized …

da76ee8

…named-value 'env'

map ObObjType to SEEKDB_TYPE in result set field metadata for C API c…

7190df3

…onsistency

fix(ci): skip macOS cert import when empty, fallback to ad-hoc signing

4edd75e

dengfuping force-pushed the feat/embedded-mode branch from f2ca5a8 to 4edd75e Compare February 28, 2026 06:32

dengfuping added 2 commits March 2, 2026 15:13

ci(compile): remove Node.js, Rust, Go setup and python3-pip from ubun…

e56d81c

…tu build

Merge branch 'master' of github.com:oceanbase/seekdb into feat/embedd…

1b25036

…ed-mode

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Add C ABI for embedded seekdb (multi‑language SDKs)#135

feat: Add C ABI for embedded seekdb (multi‑language SDKs)#135
dengfuping wants to merge 64 commits intooceanbase:masterfrom
dengfuping:feat/embedded-mode

dengfuping commented Jan 28, 2026 •

edited

Loading

Uh oh!

dengfuping commented Jan 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

dengfuping commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Task Description

Solution Description

Test Directory (unittest/include/)

Passed Regressions

Upgrade Compatibility

Other Information

Release Note

Uh oh!

dengfuping commented Jan 28, 2026

SeekDB C ABI vs MySQL 5.7 C API Complete Comparison

Document Information

Alignment Status Overview

Complete MySQL C API Function List (in official documentation order)

Basic Functions

Connection Management

Query Execution

Result Set Operations

Error Handling

Character Set

Transactions

Information Queries

Utility Functions

Database Management (Deprecated or Replaceable by SQL)

Prepared Statement API (Parameterized Queries)

Core API

Enhanced API

Thread API (Not needed in embedded mode)

Plugin API (Not needed in embedded mode)

SeekDB Extended API (Additional convenience functions)

Data Structure Alignment

SeekdbBind ↔ MYSQL_BIND (100% aligned)

SeekdbField ↔ MYSQL_FIELD (100% aligned)

SeekdbFieldType ↔ enum_field_types (100% aligned)

Alignment Summary

Core Function Alignment: 100% ✅

Overall Alignment: ~64%

Practical Usable Alignment: ~96%

Unimplemented API Evaluation and Recommendations

Evaluation Principles

Priority Classification

🔴 High Priority (Recommended to implement)

🟡 Medium Priority (Recommended to implement)

🟢 Low Priority (Optional implementation)

⚪ Not Needed

Implementation Recommendations

Key Unimplemented API Notes

Usage Recommendations

1. Code Migration

2. Function Mapping

3. Best Practices

Conclusion

Current Status Summary

Unimplemented Functions

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

dengfuping commented Jan 28, 2026 •

edited

Loading

Test Directory (`unittest/include/`)