@qualithm/rqlite-client - v0.2.3
    Preparing search index...

    Class RqliteClient

    rqlite HTTP client with connection management and authentication.

    Index

    Constructors

    constructor

    Accessors

    destroyed

    Methods

    destroy execute executeBatch get nodes post query queryBatch queryPaginated ready requestBatch serverVersion status

    Constructors

    Accessors

    • get destroyed(): boolean

      Whether this client has been destroyed.

      Returns boolean

    Methods

    • Destroy the client, aborting all in-flight and future requests.

      After calling destroy(), all pending requests will reject and any new requests will fail immediately.

      Returns void

    • Send a GET request and parse the JSON response.

      Type Parameters

      • T

      Parameters

      • path: string
      • Optionalparams: Record<string, string>
      • Optionalsignal: AbortSignal

      Returns Promise<Result<T, RqliteError>>

    • List all nodes in the rqlite cluster.

      Calls the /nodes endpoint and returns typed node information including leader status and reachability.

      Parameters

      • Optionaloptions: { nonvoters?: boolean; signal?: AbortSignal }

      Returns Promise<Result<ClusterNode[], RqliteError>>

      const result = await client.nodes()
      if (result.ok) {
        for (const node of result.value) {
          console.log(node.id, node.leader ? "(leader)" : "")
        }
      }

    post

    • post<T>(
          path: string,
          body: unknown,
          params?: Record<string, string>,
          signal?: AbortSignal,
      ): Promise<Result<T, RqliteError>>

      Send a POST request with a JSON body and parse the response.

      Type Parameters

      • T

      Parameters

      • path: string
      • body: unknown
      • Optionalparams: Record<string, string>
      • Optionalsignal: AbortSignal

      Returns Promise<Result<T, RqliteError>>

    • Execute a single SQL query (read).

      Parameters

      Returns Promise<Result<QueryResult, RqliteError>>

      // Simple query
      const result = await client.query("SELECT * FROM foo")

      // Parameterised query
      const result = await client.query("SELECT * FROM foo WHERE id = ?", [1])

      // With consistency level
      const result = await client.query("SELECT * FROM foo", undefined, { level: "strong" })

    • Execute a paginated query, yielding one page at a time.

      Appends LIMIT and OFFSET clauses to the user SQL. Each page fetches pageSize + 1 rows; if the extra row is present, hasMore is true and only pageSize rows are returned.

      Parameters

      Returns AsyncGenerator<PageResult<QueryResult>, void, undefined>

      for await (const page of client.queryPaginated(
        "SELECT * FROM large_table",
        [],
        { pageSize: 100 }
      )) {
        console.log(page.rows.values.length, page.hasMore)
      }

    • Check if the connected rqlite node is ready to accept requests.

      Calls the /readyz endpoint which returns HTTP 200 if the node is ready, or HTTP 503 if not. The noleader query parameter allows checking readiness without requiring a leader.

      Parameters

      • Optionaloptions: { noleader?: boolean; signal?: AbortSignal }

      Returns Promise<Result<ReadyResult, RqliteError>>

      const result = await client.ready()
      if (result.ok && result.value.ready) {
        console.log("node is ready, leader:", result.value.isLeader)
      }

    • Execute mixed read/write SQL statements in a single HTTP call.

      Uses the rqlite /db/request endpoint which accepts both SELECT and write statements. Each result is tagged with type: "query" or type: "execute" based on the statement.

      Parameters

      Returns Promise<Result<RequestResult[], RqliteError>>

      const results = await client.requestBatch([
        ["INSERT INTO foo VALUES(?, ?)", 1, "bar"],
        ["SELECT * FROM foo"],
      ], { transaction: true })

      if (results.ok) {
        for (const r of results.value) {
          if (r.type === "execute") console.log(r.rowsAffected)
          if (r.type === "query") console.log(r.columns, r.values)
        }
      }

    • Get the rqlite server version string.

      Extracts the build.version field from the /status endpoint. Returns undefined if the version field is not present.

      Returns Promise<Result<string | undefined, RqliteError>>

      const result = await client.serverVersion()
      if (result.ok) console.log(result.value) // "v9.4.5"

    • Get the status of the connected rqlite node.

      Returns the full status object from the /status endpoint. The structure varies by rqlite version; fields are not strictly typed.

      Returns Promise<Result<Record<string, unknown>, RqliteError>>

      const result = await client.status()
      if (result.ok) console.log(result.value)

    Settings

    Member Visibility

    On This Page

    Constructors
    Accessors
    Methods