C 레퍼런스

원문 보기 위키 갱신 2026.10.11

C 레퍼런스 (C Reference)

libSQL C 레퍼런스예요. 연결 설정부터 쿼리, 트랜잭션, 동기화까지 C 바인딩의 주요 함수를 정리했어요.

출처: 문서

본문

(기술 프리뷰 배너 스니펫: 이 기능은 기술 프리뷰 단계예요)

설치 (Installing)

libSQL C 바인딩을 사용하려면 프로젝트에 libsql.h 헤더 파일을 포함하고 liblibsql.so 공유 라이브러리에 링크해야 해요.

libSQL C — 소스 코드에서 빌드하세요.

libSQL을 사용하기 전에 setup 함수를 호출해야 해요:

libsql_setup((libsql_config_t){0});

인메모리 데이터베이스 (In-Memory Databases)

영속성이 필요 없는 경우를 위해 libSQL은 인메모리 데이터베이스 연결을 지원해요:

libsql_database_t db = libsql_database_init((libsql_database_desc_t){.path = ":memory:"});
libsql_connection_t conn = libsql_database_connect(db);

로컬 개발 (Local Development)

SQLite 파일로 로컬에서 작업할 수 있어요:

libsql_database_t db = libsql_database_init((libsql_database_desc_t){.path = "local.db"});
libsql_connection_t conn = libsql_database_connect(db);

원격 데이터베이스 (Remote Databases)

URL과 인증 토큰으로 원격 데이터베이스에 연결할 수 있어요:

libsql_database_t db = libsql_database_init((libsql_database_desc_t){
    .url = "TURSO_DATABASE_URL",
    .auth_token = "TURSO_AUTH_TOKEN"
});
libsql_connection_t conn = libsql_database_connect(db);

임베디드 복제본 (Embedded Replicas)

원격 URL에서 동기화하고 쓰기를 원격 기본(primary) 데이터베이스에 위임하는 임베디드 복제본으로 작업할 수 있어요:

libsql_database_t db = libsql_database_init((libsql_database_desc_t){
    .path = "local.db",
    .url = "TURSO_DATABASE_URL",
    .auth_token = "TURSO_AUTH_TOKEN"
});
libsql_connection_t conn = libsql_database_connect(db);

수동 동기화 (Manual Sync)

libsql_database_sync 함수로 로컬 데이터베이스와 원격 데이터베이스를 수동으로 맞출 수 있어요:

libsql_sync_t sync = libsql_database_sync(db);

동기화 주기 (Sync Interval)

데이터베이스 설명의 sync_interval 파라미터로 백그라운드 자동 동기화 주기를 설정할 수 있어요:

libsql_database_t db = libsql_database_init((libsql_database_desc_t){
    .path = "local.db",
    .url = "TURSO_DATABASE_URL",
    .auth_token = "TURSO_AUTH_TOKEN",
    .sync_interval = 60000
});

Read Your Own Writes

데이터베이스 설명의 not_read_your_writes 파라미터는 같은 연결에서 시작된 이후 읽기 연산에 쓰기가 즉시 보이도록 데이터베이스 연결을 구성해요. 기본으로 활성화되어 있고, not_read_your_writes를 true로 설정하면 끌 수 있어요:

libsql_database_t db = libsql_database_init((libsql_database_desc_t){
    .path = "local.db",
    .url = "TURSO_DATABASE_URL",
    .auth_token = "TURSO_AUTH_TOKEN",
    .not_read_your_writes = true
});

간단한 쿼리 (Simple query)

파라미터가 없는 간단한 쿼리에는 libsql_connection_batch를 사용할 수 있어요:

libsql_batch_t batch = libsql_connection_batch(conn, "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)");

결과가 있는 쿼리에는 libsql_connection_prepare와 libsql_statement_query를 사용하세요:

libsql_statement_t stmt = libsql_connection_prepare(conn, "SELECT * FROM users");
libsql_rows_t rows = libsql_statement_query(stmt);

준비된 문 (Prepared Statements)

libsql_connection_prepare로 문을 준비한 다음 libsql_statement_execute나 libsql_statement_query로 실행할 수 있어요:

libsql_statement_t stmt = libsql_connection_prepare(conn, "INSERT INTO users (name) VALUES (?)");
libsql_statement_bind_value(stmt, libsql_text("John Doe", 8));
libsql_execute_t result = libsql_statement_execute(stmt);

플레이스홀더 (Placeholders)

libSQL은 SQL 문 안에서 위치 기반(positional)과 이름 기반(named) 플레이스홀더를 지원해요:

위치 기반(Positional):

libsql_statement_t stmt = libsql_connection_prepare(conn, "SELECT * FROM users WHERE id = ?");
libsql_statement_bind_value(stmt, libsql_integer(1));

이름 기반(Named):

libsql_statement_t stmt = libsql_connection_prepare(conn, "SELECT * FROM users WHERE id = :id");
libsql_statement_bind_named(stmt, ":id", libsql_integer(1));

트랜잭션 (Transactions)

libSQL은 트랜잭션을 지원해요:

libsql_transaction_t tx = libsql_connection_transaction(conn);
// Perform operations within the transaction
libsql_transaction_commit(tx); // or libsql_transaction_rollback(tx)

정리 (Cleanup)

작업을 마쳤으면 자원을 정리하는 걸 잊지 마세요:

libsql_statement_deinit(stmt);
libsql_connection_deinit(conn);
libsql_database_deinit(db);