본문 바로가기
WIKI 기술 지식 베이스

libSQL PHP 레퍼런스

원문 보기 위키 갱신

libSQL PHP 클라이언트의 전체 API를 정리한 레퍼런스예요. 설치부터 인메모리·로컬·원격·임베디드 레플리카 연결, 쿼리와 트랜잭션까지 PHP 애플리케이션에서 필요한 모든 기능을 담고 있어요.

출처: 문서

본문

설치 (Installing)

composer로 프로젝트에 패키지를 설치해요.

composer require turso/libsql

초기화 (Initializing)

Database 객체를 사용하려면 use Libsql\Database를 추가해야 해요.

$db = new Database("local.db")

인메모리 데이터베이스

영속성이 필요 없는 경우라면 libSQL의 인메모리 데이터베이스 연결을 활용할 수 있어요.

$db = new Database(":memory:");

또는 더 간단하게 이렇게 써도 돼요.

$db = new Database();

로컬 개발

첫 번째 파라미터로 경로를 넘기면 로컬에서 작업할 수 있어요.

$db = new Database("local.db")

또는 더 명시적으로 이렇게 써도 돼요.

$db = new Database(path: "local.db")

원격 전용 (Remote Only)

url과 authToken을 넘기면 원격 전용 데이터베이스를 사용할 수 있어요.

$db = new Database(
    url: getenv('TURSO_URL'),
    authToken: getenv('TURSO_AUTH_TOKEN'),
);

임베디드 레플리카

path, url, authToken을 넘기면 임베디드 레플리카를 사용할 수 있어요. 임베디드 레플리카는 원격 URL에서 동기화하고 쓰기는 원격 primary 데이터베이스에 위임해요.

$db = new Database(
    path: 'test.db',
    url: getenv('TURSO_URL'),
    authToken: getenv('TURSO_AUTH_TOKEN'),
);

동기화 간격 (Sync Interval)

sync_interval 함수를 쓰면 데이터베이스를 백그라운드에서 자동 동기화하는 간격을 설정할 수 있어요.

$db = new Database(
    path: 'test.db',
    url: getenv('TURSO_URL'),
    authToken: getenv('TURSO_AUTH_TOKEN'),
    syncInterval: 300, // Sync every 3 seconds
);

수동 동기화 (Manual Sync)

sync 함수를 쓰면 로컬 데이터베이스를 원격 데이터베이스와 직접 동기화할 수 있어요.

$db->sync()

자신이 쓴 내용 읽기 (Read Your Own Writes)

readYourWrites 파라미터는 같은 커넥션이 시작한 이후 읽기 작업에서 쓰기 내용이 바로 보이도록 데이터베이스 연결을 설정해요. 기본값은 켜짐이고, 쓰기 프로세스 관점에서 일관성을 보장하려는 분산 시스템에서 특히 중요해요.

false를 넘기면 이 동작을 끌 수 있어요.

$db = new Database(
    path: 'test.db',
    url: getenv('TURSO_URL'),
    authToken: getenv('TURSO_AUTH_TOKEN'),
    readYourWrites: false,
);

단순 쿼리 (Simple Query)

데이터베이스에서 커넥션을 얻은 뒤 query()를 호출해 SQL 문과 선택적인 인자를 실행할 수 있어요.

$rows = $conn->query("SELECT * FROM users");

$rows = $conn->query("SELECT * FROM users WHERE id = ?1", [1]);

$rows = $conn->query("SELECT * FROM users WHERE id = :id", [":id" => 1]);

프리페어드 스테이트먼트 (Prepared Statements)

prepare()로 캐시된 문을 만들고, 파라미터를 바인딩한 뒤 쿼리할 수 있어요.

$stmt = $conn->prepare("SELECT * FROM users where id = ?");
$rows = $stmt->bind([1])->query();

플레이스홀더

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

conn->query("SELECT * FROM users WHERE id = ?", [1]);

conn->execute("INSERT INTO users (name) VALUES (:name)", [ ":name" => "Iku" ]);

배치 트랜잭션 (Batch Transactions)

배치는 여러 SQL 문을 묶어서 암시적 트랜잭션 안에서 순차 실행하는 방식이에요. 트랜잭션 처리는 백엔드가 담당해서, 성공하면 모든 변경 사항이 커밋되고 실패하면 전체 롤백되어 아무것도 수정되지 않아요.

$conn->execute_batch("
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL
  );

  INSERT INTO users (name) VALUES ('Alice');
  INSERT INTO users (name) VALUES ('Bob');
");

인터랙티브 트랜잭션 (Interactive Transactions)

SQLite의 인터랙티브 트랜잭션은 트랜잭션 범위 안에서 일련의 읽기·쓰기 작업이 일관성을 유지하도록 보장해요. 커밋할지 롤백할지 시점을 직접 제어할 수 있고, 다른 클라이언트 활동으로부터 격리돼요.

$tx = conn->transaction();

$tx->execute("INSERT INTO users (name) VALUES (?1)", ["Iku"]);
$tx->execute("INSERT INTO users (name) VALUES (?1)", ["Iku 2"]);

tx->commit(); // or, $tx->rollback()

더 알아보기 (Learn more)