Skip to content
Nappai Documentation

libSQL

libSQL is a simple way to read from, write to, and explore your Turso (libSQL) databases right from the Nappai dashboard. Whether you want to add new rows, run a custom query, build a search retriever, or just look at the database structure, this component gives you a single place to do it.

How it Works

When you drop the libSQL component onto your workflow, it connects to the Turso database you selected in the Credential field. That credential holds the URL and token needed to talk to the database. Once connected, the component can:

  • Add rows to a table, optionally dropping the table first.
  • Run a SQL query you write in the editor.
  • Build a Retriever that can find similar rows using embeddings.
  • Pull Database Info such as table names and column types.

All of this happens through Turso’s REST API, so you don’t need to write any code—just set the fields and click Run.

Operations

This component offers several operations that you can select based on what you need to do. You can only use one operation at a time:

  • Add: Insert new data into a table, optionally dropping the table first.
  • SQL: Execute a custom SQL query and return the results.
  • Retriever: Build a retriever that can perform similarity search on the table’s data.
  • DatabaseInfo: Retrieve metadata about the database, such as tables and columns.

To use the component, first select the operation you need in the Operation field.

Inputs

The following fields are available to configure this component. Each field may be visible in different operations:

  • Embedding: Embedding to generate vector from text or to use similarity search.

    • Visible in: Add, SQL, Retriever

  • Ingest Data: Insert data into the database table.

    • Visible in: Add

  • Operation: Choose which operation to run.

    • Visible in: Add, SQL, Retriever, DatabaseInfo

  • Number of Results: Number of results to return.

    • Visible in: Add, SQL, Retriever, DatabaseInfo

  • Search Query: SQL query to execute.

    • Visible in: SQL

  • Search Score Threshold: If value is distinct to 0.0, it will filter the results with distance score lower than the threshold.

    • Visible in: Add, SQL, Retriever, DatabaseInfo

  • Table Name: Name of the table in the database.

    • Visible in: Add

  • Drop Table: Drop the table if it exists before inserting data.

    • Visible in: Add, DatabaseInfo

Credential: The component has a special field called Credential where you select a libSQL/Turso credential that you must configure first.

  1. Go to the Credentials section of Nappai and add a new libSQL / Turso credential, providing the URL and Token.
  2. Back in the component, choose that credential from the Credential dropdown.

Outputs

  • Data: The raw data returned from a query or the result of an Add operation.
  • Retriever: A retriever object that can be used for similarity search.
  • Database Info: Metadata about the database (tables, columns, etc.).
  • Database Schema: The schema of the selected table as a data object.

Usage Example

Example 1 – Adding Data

  1. Drag the libSQL component onto the canvas.
  2. Set Operation to Add.
  3. Enter the Table Name (e.g., customers).
  4. Toggle Drop Table if you want to start fresh.
  5. In Ingest Data, paste a JSON array of rows.
  6. Set Number of Results to 10 if you want to see the inserted rows.
  7. Click Run. The Data output will show the inserted rows.

Example 2 – Running a Custom Query

  1. Drag the libSQL component onto the canvas.
  2. Set Operation to SQL.
  3. In Search Query, type: 
    SELECT * FROM customers WHERE country = 'USA' LIMIT 5;
  4. Set Number of Results to 5.
  5. Click Run. The Data output will contain the query results.
  • Data Ingest – Load data from files or APIs into a workflow.
  • SQL Query – Execute SQL against a database without the extra features of libSQL.
  • Retriever – Build a similarity search retriever from any data source.
  • Database Info – Get metadata from any supported database.

Tips and Best Practices

  • Use the correct table name – Typos will cause the operation to fail.
  • Match your data to the table schema – Inconsistent columns can lead to errors.
  • Set a reasonable Number of Results – Large queries can slow down the workflow.
  • Use Search Score Threshold to filter out low‑similarity results when building a retriever.
  • Keep your credentials secure – Never expose the URL or token in public workflows.

Security Considerations

  • Store the libSQL/Turso credential in Nappai’s secure credential store.
  • Do not share the credential or its details with unauthorized users.
  • When using the SQL operation, validate any user‑supplied query to avoid injection attacks.