Using Database

Cloud Flow can read and modify Project Database records through visual Database blocks and the $io.db Server API. Use these capabilities when a backend workflow needs to work with Project data—for example, to validate a registration, retrieve records for processing, update an order, or generate files associated with a record.

This guide focuses on implementing Database operations inside Cloud Flow. For the broader architecture, authorization model, and reasons to choose Cloud Flow instead of browser-side data access, see Using Database from Cloud Flow.

Choosing How to Access Database

Cloud Flow provides two complementary implementation approaches:

Approach	Use It When
Cloud Flow Database blocks	The operation can be expressed clearly through visual blocks, including reads, lookups, creates, updates, deletes, and dataset operations.
$io.db Server API in Custom Code	You need focused JavaScript, a more specialized Database operation, or an API capability not exposed through the available blocks.

Both approaches run on the server. You can use blocks for the main workflow and Custom Code for a specialized operation within the same module.

The Server $io.db API offers more methods and functionality than the Client $io.db API. Built-in frontend Forms, Widgets, Page Flow blocks, and custom frontend JavaScript use the Client API. Cloud Flow can use the broader Server API, including server-side capabilities such as additional match-based operations, aggregate reads, Database trigger hooks, and table-file processing documented in the Server API reference.

Do not assume that a server-side function is available in the browser or that similarly named Client and Server methods have identical parameters or behavior.

Common Database Operations

Operation	Typical Cloud Flow Use	Implementation Consideration
Read or query	Retrieve records matching a named query or other supported criteria.	Check results before proceeding; handle empty results separately from failures.
Lookup	Find one record or retrieve a record by ID.	Handle a missing record and verify access to the requested record.
Create	Add a record after validation.	Check required fields, authorization, and duplicate requests.
Update by ID	Change a known record.	Confirm the ID identifies the intended record and the change is allowed.
Delete by ID	Remove a specific record.	Check authorization and impacts on related records and files.
Update or delete by match	Apply an operation to records selected by supported match criteria.	Review the criteria carefully; avoid unintentionally modifying many records.
Count	Determine the number of records satisfying a condition.	Distinguish a full match count from the number of records in one loaded dataset page.
File operations	Create, read, transfer, or delete files associated with records.	Respect the table's file-access model and the specific file operation's permissions.

The exact available blocks and methods are listed in the Cloud Flow Database Blocks and $io.db Server API references. These references are the authoritative source for parameter types, match formats, and result structures.

Building a Database Workflow

A typical Cloud Flow implementation follows these steps:

1. Open Backend → Cloud Flow and select the Background Task or Web Hook that will use the Database.
2. Choose Edit Flow to open its canvas.
3. Select the appropriate Database blocks, or use Custom Code when the Server API is a better fit.
4. Identify the table, record ID, query, or match criteria needed by the operation.
5. Validate incoming values and establish the caller's authorization where relevant.
6. Run the Database operation and handle its completion or returned result.
7. Continue only when the operation succeeds; provide a clear failure path otherwise.
8. Save the module and test it through its intended execution path.

A Web Hook usually receives input from Page Flow, custom frontend JavaScript, or an external caller and returns an HTTP response. A Background Task performs the operations defined by its own backend logic; it has no separate trigger or scheduling configuration.

For editor navigation and block editing, see Cloud Flow Editor.

Reading Records and Named Queries

Named Queries provide reusable retrieval patterns defined under a Database table. A Cloud Flow can use them to load records for validation, processing, or a controlled response.

For example, a RegistrationsByEvent query can retrieve registrations associated with a selected event. Its Search Criteria, Field Selection, Data Joins, and Sorting Order are configured in Queries. The Cloud Flow supplies the runtime input identifying the event.

Visual Block Approach

The Cloud Flow Database block family includes Data Read, Data Query Name, Data Status, dataset record operations, and next/previous page operations.

A typical block-based sequence is:

Validate event ID and authorization
  Read Registrations using RegistrationsByEvent
  Check Data Status after the read completes
  If successful
    Process the returned records
  Otherwise
    Record the failure and return an appropriate result

This is a conceptual sequence, not a substitute for the documented block connections or asynchronous behavior.

Server API Approach

For direct JavaScript, the Server API documents $io.db.readQuery with an ordered queryInput array:

// Assumes eventId has already been validated and access has been checked.
const result = await $io.db.readQuery(
  'Registrations',
  'eventRegistrations',
  25,
  'RegistrationsByEvent',
  [eventId],
  {}
);

if (!result.status) {
  // Handle result.err; do not proceed as though records were loaded.
} else {
  const registrations = result.data;
  // Process the records returned by this read.
}

Replace the example table name, query name, dataset name, and input with your Project's actual configuration. The values in queryInput must follow the parameter order defined by the query. The example demonstrates a completed read; it does not implement the preceding caller-authentication and authorization checks.

Dataset and paging behavior matters. The current page of records is not necessarily the complete query result. For a full matching count, use a supported count operation rather than assuming the current-page record count is the total. The Server API also documents asynchronous options such as noWait, waitForCompletion, and dataset-reading functions; follow that contract when choosing non-default execution behavior.

Creating, Updating, and Deleting Records

Cloud Flow can perform record writes after verifying the request and current data.

For example, an order-update workflow can:

1. Receive the order ID and requested change.
2. Validate the request and identify the caller using trustworthy context.
3. Read the existing order and confirm it is the intended record.
4. Check whether the caller can modify that order and whether the status transition is allowed.
5. Update the record using the appropriate Database block or Server API method.
6. Check the result and return only the information the caller needs.

Operations by ID and by Match

Use by-ID operations when the workflow has already identified a particular record. The Server API and Cloud Flow block references also document by-match operations for supported updates and deletes.

Match-based operations can affect multiple records. Confirm the criteria with representative data, and avoid using broad matches where a single-record update is intended.

Related Records and Repeated Requests

A workflow may need to create or modify several related records. Multiple Database calls are not automatically one atomic transaction. Design explicitly for partial failures and for requests that may be retried.

For operations such as registration creation or order fulfillment, determine how the workflow prevents unintended duplicate effects and handles changes made by concurrent callers. Do not assume that counting records and then creating a new record automatically enforces a capacity limit under concurrent requests.

Additional Server Database Capabilities

The Server API includes specialized operations beyond ordinary record CRUD, including documented methods for:

• Aggregate and match-based reads and counts.
• Database trigger hooks.
• Files attached to Database records, including reading, creating, copying, and deleting supported file data.
• Dataset management and paged record processing.

Choose these capabilities when they match the backend requirement rather than attempting to reproduce their behavior through browser-side code. Some are available through Cloud Flow blocks; others may require direct $io.db Server API calls. Check the appropriate reference for each operation.

For Database trigger hooks, review the documented $io.db.setTriggerHook contract before implementing callbacks or depending on their timing and execution context.

Working with File Fields

Cloud Flow can process files associated with Database records, including generated documents and uploaded attachments. For specialized server-side file operations, use the $io.db table-file methods or appropriate $io.fs functionality.

Files associated with Database file fields inherit the access rules of their parent table. If a table allows public Read access, its associated file-field content should be treated as publicly accessible. Returning a file link only after a Web Hook authorization check does not, by itself, change the file's underlying table-based access permissions.

Use a suitable restricted table or another controlled storage and delivery design for confidential attachments. See File Fields and Using Files.

Example: Processing an Event Registration

Consider a Web Hook that processes a registration request.

Registration Web Hook
  Receive submitted event and attendee information
  Validate the request and caller
  Retrieve current event information
  Check eligibility and enforce capacity rules safely
  Create the registration if permitted
  Handle any Database failure or duplicate request
  Return a limited success or error result

The key responsibility is not merely creating a record. The Web Hook must decide whether the operation is allowed and avoid treating untrusted Page input as an authorization fact.

If a Page calls this Web Hook, the Page can use the result to show a confirmation, display an error, or refresh its registration list. For the request/response details, see Calling Cloud Flow from Pages.

Testing Database Operations

Test each workflow through the execution path that will use it—such as a Page in Preview, an external Web Hook caller, or the Background Task's own logic.

During Page Preview, built-in Database operations automatically use the Project's development database. The published Project uses its production data environment. Confirm the applicable runtime and data environment for other testing paths and external Connections rather than assuming that every operation is isolated from production services.

Verify the following cases:

Case	What to Verify
Successful operation	The correct records are read or modified and the expected result is returned.
No matching record	The workflow handles the absence of data without treating it as an unexpected success.
Invalid input	The operation is rejected before an unintended write.
Unauthorized request	No restricted records or files are exposed or modified.
Multiple matches	By-match operations do not affect more records than intended.
Repeated requests	Retries do not cause unintended duplicate changes.
Partial failure	Related updates and external calls leave the workflow in a known, recoverable state.
External failure	Integration errors are handled without falsely reporting Database success.

Use Testing and Logs to inspect backend activity. Avoid logging credentials or unnecessary sensitive record values.

Good Practices

• Choose blocks or Server API methods intentionally. Use the supported interface that makes the operation easiest to maintain.
• Use server-only capabilities when needed. Do not assume Client and Server $io.db have identical functionality.
• Validate before writes. Authenticate and authorize the caller where applicable, then verify the target record and business rules.
• Keep queries reusable. Use named queries for shared retrieval patterns and supply their parameters correctly.
• Handle completion and failure. A started Database operation is not necessarily a completed one.
• Limit returned data. Return only what the frontend or other caller requires.
• Test repeated and concurrent work. Consider duplicate requests, overlapping changes, and partial failures.

Common Mistakes

Avoid these patterns:

• Using browser-provided record IDs or role values as proof of authorization.
• Assuming a query itself grants permission to read the returned records.
• Calling a server-only $io.db method from frontend code.
• Treating the record count on one loaded dataset page as a full query count.
• Updating or deleting by match without checking how many records may be affected.
• Assuming several separate Database writes are automatically transactional.
• Treating files attached to a publicly readable table as private.
• Returning complete records when a caller needs only a status or small summary.

Cloud Flow provides trusted Database processing and access to the broader Server API. Use its Database blocks and server-side code to implement operations that are correct, authorized, and maintainable.

Technical Reference

• Cloud Flow Database Blocks
• $io.db Server API
• Result Objects

Related Topics

• Using Database from Cloud Flow
• Queries
• Table Access
• File Fields
• Access Security
• Calling Cloud Flow from Pages
• Testing and Logs