apache / apache/arrow-adbc

Document dlclose restrictions for Go-based (cgo) drivers

Open
#4,210 2 comments 0 reactions 0 assignees View on GitHub
Type: enhancement
Dominant language
C#
Stars
627
Forks
217
Avg merge
17h
Merged PRs (30d)
57

Description

### What feature or improvement would you like to see?

Following up on the discussion in https://github.com/apache/arrow-adbc/discussions/4206#discussioncomment-16550014

- **Go-based drivers** (Flight SQL, Snowflake): `dlclose` hangs or crashes because the Go runtime does not support clean unload (golang/go#11100). The Rust driver manager already works around this by skipping `dlclose` (#3844, https://github.com/apache/arrow-adbc/pull/3291), but this is not documented in the C API.
- **C/C++ drivers** (SQLite, PostgreSQL): presumably safe, but not documented either.
- **Rust drivers**: untested per maintainer.

Embedders integrating the C driver manager (e.g., StarRocks, DuckDB) currently have to discover this through the Rust manager's changelog or by debugging hangs at process shutdown.

**Proposal**: add a section to the C driver manager (maybe for JNI part as well) documentation covering:

1. `dlclose` must not be called on Go-based driver handles. Driver handles should stay resident until process exit.
2. Cleanup should go through the ADBC API only: `AdbcStatementRelease` -> `AdbcConnectionRelease` -> `AdbcDatabaseRelease`.
3. Multiple Go-based drivers can be `dlopen`-ed in the same process on Linux and ARM macOS, but not on Intel macOS (due to an unresolved Go runtime bug).

Contributor guide

Open the contributing guide

Research direction

Start with the C driver manager documentation and the linked discussion in issue #4210. Check how the Rust driver manager handles dlclose and confirm the documented Go, C/C++, and Rust behavior before adding guidance for the ADBC cleanup sequence and platform limitations. Done means embedders can find these restrictions in the C API documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
c, go
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.