키-값 스토어

store 모듈은 선택적 TTL을 지원하는 키-값 스토리지를 제공합니다. 캐시 데이터, 세션 및 기타 임시 상태를 보관할 수 있습니다.

이 페이지는 API 참조입니다. 코드 조각은 구성된 스토어, 아래에 나열된 권한, owner 또는 new_value 같은 애플리케이션 제공 값을 가정합니다. 획득 이후의 코드 조각은 기존의 활성 cache 핸들을 사용하며 독립 실행 함수가 아닙니다.

스토어 설정은 스토어를 참조하세요.

로딩

local store = require("store")

스토어 획득

레지스트리 ID로 스토어 리소스 가져오기:

local cache, err = store.get("app:cache")
if err then
    return nil, err
end

local _, set_err = cache:set("user:123", {name = "Alice"}, 3600)
if set_err then
    cache:release()
    return nil, set_err
end

local user, get_err = cache:get("user:123")

cache:release()
if get_err then return nil, get_err end
return user

반환: Store, error

값 저장

선택적 TTL과 함께 값 저장:

-- Simple set
local _, err = cache:set("user:123:name", "Alice")
if err then return nil, err end

-- Set with TTL (expires in 300 seconds)
local ok, ttl_err = cache:set("session:abc", {user_id = 123, role = "admin"}, 300)
if ttl_err then return nil, ttl_err end
return ok

반환: boolean, error

값 조회

키로 값 가져오기:

local errors = require("errors")

local user, err = cache:get("user:123")
if err then
    if err:kind() == errors.NOT_FOUND then
        return nil -- key missing or expired
    end
    return nil, err
end
return user

반환: any, error

키가 존재하지 않거나 만료된 경우 nil과 errors.NOT_FOUND 에러를 반환합니다.

존재 확인

조회하지 않고 키 존재 확인:

if cache:has("lock:" .. resource_id) then
    return nil, errors.new({ kind = errors.CONFLICT, message = "Resource is locked" })
end

반환: boolean, error

키 삭제

스토어에서 키 제거:

local deleted, err = cache:delete("session:" .. session_id)
if err then return nil, err end
return deleted

반환: boolean, error

삭제되면 true, 키가 존재하지 않았으면 false 반환.

엔트리 메타데이터 읽기

entry는 값과 함께 낙관적 동시성에 사용되는 불투명한 문자열인 version을 반환합니다.

local e, err = cache:entry("user:123")
if err then return nil, err end
if e then
    print(e.key, e.value, e.version)
end

반환: Entry, error — {key: string, value: any, version: string}

키 목록

페이징과 함께 결정적 키 순서로 엔트리 나열:

local page, err = cache:list({ prefix = "session:", limit = 100 })
if err then return nil, err end
for _, e in ipairs(page.items) do
    print(e.key, e.value)
end

-- next page
if page.has_more then
    local next_page, next_err = cache:list({ prefix = "session:", after = page.cursor })
    if next_err then return nil, next_err end
    page = next_page
end

반환: Page, error — {items: Entry[], cursor: string, has_more: boolean}

조건부 쓰기

put은 값을 쓰고 새 Entry를 반환합니다. 옵션으로 낙관적 동시성을 활성화합니다:

local errors = require("errors")

-- create only if the key does not exist
local e, err = cache:put("lock:job-1", owner, { only_if_absent = true })
if err and err:kind() == errors.ALREADY_EXISTS then
    -- 다른 누군가가 보유 중
end

-- compare-and-set: write only if the version still matches
local cur, read_err = cache:entry("config")
if read_err then return nil, read_err end
local e2, err2 = cache:put("config", new_value, { if_version = cur.version })
if err2 and err2:kind() == errors.CONFLICT then
    -- 동시 쓰기가 이를 변경함; 다시 읽고 재시도
end

only_if_absent와 if_version은 상호 배타적입니다.

반환: Entry, error

스토어 기능

info는 백엔드와 지원하는 기능을 보고하므로, 코드가 바인딩된 스토어에 맞춰 적응할 수 있습니다:

local info, err = cache:info()
if err then return nil, err end
-- info.backend      -> one of store.backend.* (e.g. "kv.raft")
-- info.consistency  -> one of store.consistency.* (e.g. "linearizable")
-- info.durable / info.list / info.versioned / info.conditional_put / info.ttl  (booleans)

반환: Info, error — {id, backend, consistency, durable, list, versioned, conditional_put, ttl}

상수

local info, err = cache:info()
if err then return nil, err end
if info.consistency == store.consistency.LINEARIZABLE then
    -- safe to use compare-and-set
end

스토어 메서드

권한

스토어 작업은 보안 정책 평가 대상입니다.

에러

store.get()과 스토어 핸들의 모든 메서드(get, entry, set, put, list, has, delete, info)는 구조화된 오류를 반환합니다(err:kind() 사용). 단, store.get, get, set, has, delete에서의 권한 거부는 대신 Lua 에러로 발생합니다.

에러 처리는 에러 처리를 참조하세요.