Edge Functions

Edge Functions are server-side functions that run directly within your database environment. Edge functions in SQLite Cloud ensure maximum performance and minimal latency by running functions on the same server as your database.

You can write edge functions directly in the SQLite Cloud dashboard using JavaScript, TypeScript, or SQL. Importing modules is not currently supported.

Edge functions can be called remotely over HTTP or Websockets via API, or triggered by database events via SQLite Cloud Webhooks. Each function runs in an isolated environment using the Bun runtime.

Turning on linearizable reads ensures strong consistency, but may introduce some latency. When eventual consistency is sufficient, we recommend leaving linearizable reads off.

Getting Started

1. Navigate to the Edge Functions page from your dashboard.
2. Under “Development”, select “Edge Function”, then click the “Create” button.
3. Write and test your function.
   1. Select the database you want to access and an API key if necessary
   2. When you’re finished, click deploy.

Note:

Functions should return a JSON-serializable object with a data field:

return {
  data: {
    // your return object
  }
}

Authorization

Edge functions that access your SQLite databases must be authorized via API key. You can automatically authorize an edge function on every call by assigning it an API key via the “API KEY” dropdown.

If no API key is assigned, an API key must be sent in the request url as a query parameter (?apikey=YOUR_API_KEY) or as an attribute in the request body ({ apikey: YOUR_API_KEY }).

Execution

Edge functions can be called via HTTP GET and POST methods. You can pass additional values to your edge function in two ways:

• Query parameters: Accessible via request.params
• Request body: Accessible via request.data

Testing

You may test the execution of edge functions by clicking the “Test” command.

You are not required to supply an API key when testing your edge function in the console. The function will run using the dashboard user privileges.

Guides

Interacting with your Database

Use the global connection object to access and manipulate your database.

const customers = await connection.sql`SELECT * FROM customers;`
return {
  data: customers
}

Select the database you would like to access from the “Database” dropdown, or select the database you want to use in your SQL query with the USE command.

const customers = await connection.sql`USE DATABASE chinook.sqlite; SELECT * FROM customers;`;
return {
  data: customers
}

Storing and Accessing Environment Variables

Environment variables can be accessed and stored with the ENV command. ENV variables are stored in the server settings file and are project-specific. Use the following commands to set and read values in your server settings file:

• LIST ENV
• SET ENV key VALUE value
• GET ENV key
• REMOVE ENV key

You can also add environment variables in the UI by navigating to the “Environment Variables” section and clicking the “Create” button.

Handling Errors

In case of error we return an HTTP error code and a JSON with the error message. Manually throwing an error in your code results in a 500 response. You may also return an error.

Examples

Assigning and Notifying a Support Rep on User Sign up

// Get secret from database
const slackWebhookEndpoint = await connection.sql`GET ENV slack_webhook_endpoint`;

// Get record sent in body via webhook
const content = request.data;
const database = content.database;
const primaryKey = content.data[0];
const newCustomer = await connection.sql`USE DATABASE ${database}; SELECT * FROM customers WHERE CustomerId = ${primaryKey};`;

// Sample business logic - assign and notify support rep
// Get reps from database
const reps = await connection.sql`SELECT id, name, country FROM reps`;
const rep = reps.find(({ country }) => country === newCustomer.country.toLowerCase());

// Define helpers to assign and notify
const assignRep = async (repId, customerId) => await connection.sql`UPDATE customers SET SupportRepId = ${repId} WHERE CustomerId = ${customerId}`;
const notifyRep = async (repName, customer) => {
    const message = `@${repName}: New User Sign Up - ${JSON.stringify(customer)}`
    try {
        await fetch(slackWebhookEndpoint, { body: JSON.stringify({ text: message }), method: 'POST', 'Content-type': 'application/json'  });
    } catch (err) {
        await fetch(slackWebhookEndpoint, { body: JSON.stringify({ text: err }), method: 'POST', 'Content-type': 'application/json'  });
    }
} 

// Call async functions
await assignRep(rep.id, newCustomer.id);
await notifyRep(rep.name, newCustomer);

return {
    data: 'OK'
}