Cal.com

Cal.com is an open source scheduling platform.

The Cal Wrapper is a WebAssembly(Wasm) foreign data wrapper which allows you to read data from your Cal.com account for use within your Postgres database.

Available Versions#

Preparation#

Before you can query Cal.com, you need to enable the Wrappers extension and store your credentials in Postgres.

Enable Wrappers#

Make sure the wrappers extension is installed on your database:

1
create extension if not exists wrappers with schema extensions;

Enable the Cal.com Wrapper#

Enable the Wasm foreign data wrapper:

1
create foreign data wrapper wasm_wrapper
2
  handler wasm_fdw_handler
3
  validator wasm_fdw_validator;

Store your credentials (optional)#

By default, Postgres stores FDW credentials inside pg_catalog.pg_foreign_server in plain text. Anyone with access to this table will be able to view these credentials. Wrappers is designed to work with Vault, which provides an additional level of security for storing credentials. We recommend using Vault to store your credentials.

1
-- Save your Cal.com API key in Vault and retrieve the created `key_id`
2
select vault.create_secret(
3
  '<Cal.com API key>', -- Cal.com API key
4
  'cal',
5
  'Cal.com API key for Wrappers'
6
);

Connecting to Cal.com#

We need to provide Postgres with the credentials to access Cal.com and any additional options. We can do this using the create server command:

1
create server cal_server
2
  foreign data wrapper wasm_wrapper
3
  options (
4
    fdw_package_url 'https://github.com/supabase/wrappers/releases/download/wasm_cal_fdw_v0.1.0/cal_fdw.wasm',
5
    fdw_package_name 'supabase:cal-fdw',
6
    fdw_package_version '0.1.0',
7
    fdw_package_checksum '4afe4fac8c51f2caa1de8483b3817d2cec3a14cd8a65a3942c8b4ff6c430f08a',
8
    api_url 'https://api.cal.com/v2',  -- optional
9
    api_key_id '<key_ID>' -- The Key ID from above.
10
  );

Note the fdw_package_* options are required, which specify the Wasm package metadata. You can get the available package version list from above.

Create a schema#

We recommend creating a schema to hold all the foreign tables:

1
create schema if not exists cal;

Options#

The full list of foreign table options are below:

• object - Object name in Cal.com, required.

Supported objects are listed below:

Entities#

The Cal.com Wrapper supports data reads and booking writes from the Cal.com API.

We can use SQL import foreign schema to import foreign table definitions from Cal.com.

For example, using below SQL can automatically create foreign tables in the cal schema.

1
-- create all the foreign tables
2
import foreign schema cal from server cal_server into cal;
3
4
-- or, create selected tables only
5
import foreign schema cal
6
   limit to ("event_types", "bookings")
7
   from server cal_server into cal;
8
9
-- or, create all foreign tables except selected tables
10
import foreign schema cal
11
   except ("event_types")
12
   from server cal_server into cal;

Profile#

This is an object representing your Cal.com user profile.

Ref: Cal.com API docs

Operations#

Usage#

1
create foreign table cal.my_profile (
2
  id bigint,
3
  username text,
4
  email text,
5
  attrs jsonb
6
)
7
  server cal_server
8
  options (
9
    object 'my_profile'
10
  );

Notes#

• The attrs column contains all profile attributes in JSON format

Event Types#

This is an object representing Cal.com event types.

Ref: Cal.com API docs

Operations#

Usage#

1
create foreign table cal.event_types (
2
  attrs jsonb
3
)
4
  server cal_server
5
  options (
6
    object 'event-types'
7
  );

Notes#

• The attrs column contains all event type attributes in JSON format
• Extract specific fields using JSON operators, for example:

  1
  select
  2
    etg->'profile'->>'name' as profile,
  3
    et->>'id' as id,
  4
    et->>'title' as title
  5
  from cal.event_types t
  6
    cross join json_array_elements((attrs->'eventTypeGroups')::json) etg
  7
    cross join json_array_elements((etg->'eventTypes')::json) et;

Bookings#

This is an object representing Cal.com bookings.

Ref: Cal.com API docs

Operations#

Usage#

1
create foreign table cal.bookings (
2
  attrs jsonb
3
)
4
  server cal_server
5
  options (
6
    object 'bookings',
7
    rowid_column 'attrs'
8
  );

Notes#

• Supports both reading and creating bookings
• The attrs column contains all booking attributes in JSON format
• Example of creating a booking:

  1
  insert into cal.bookings(attrs)
  2
  values (
  3
    '{
  4
      "start": "2024-12-12T10:30:00.000Z",
  5
      "eventTypeId": 123456,
  6
      "attendee": {
  7
        "name": "Test Name",
  8
        "email": "test.name@example.com",
  9
        "timeZone": "America/New_York"
  10
      }
  11
    }'::jsonb
  12
  );
• Additional fields like guests or metadata can be added to the booking JSON
• For more details on booking options, refer to Cal.com documentation

Calendars#

This is an object representing Cal.com calendars.

Ref: Cal.com API docs

Operations#

Usage#

1
create foreign table cal.calendars (
2
  attrs jsonb
3
)
4
  server cal_server
5
  options (
6
    object 'calendars'
7
  );

Notes#

• The attrs column contains all calendar attributes in JSON format

Schedules#

This is an object representing Cal.com schedules.

Ref: Cal.com API docs

Operations#

Usage#

1
create foreign table cal.schedules (
2
  id bigint,
3
  name text,
4
  attrs jsonb
5
)
6
  server cal_server
7
  options (
8
    object 'schedules'
9
  );

Notes#

• The attrs column contains additional schedule attributes in JSON format

Conferencing#

This is an object representing Cal.com conferencing settings.

Ref: Cal.com API docs

Operations#

Usage#

1
create foreign table cal.conferencing (
2
  id bigint,
3
  attrs jsonb
4
)
5
  server cal_server
6
  options (
7
    object 'conferencing'
8
  );

Notes#

• The attrs column contains all conferencing attributes in JSON format

Query Pushdown Support#

This FDW doesn't support query pushdown.

Supported Data Types#

The Cal.com API uses JSON formatted data, please refer to Cal.com API docs for more details.

Limitations#

This section describes important limitations and considerations when using this FDW:

• Only supports Cal.com API v2
• Large result sets may experience slower performance due to full data transfer requirement
• Write operations limited to booking creation only
• Materialized views using these foreign tables may fail during logical backups

Examples#

Below are some examples on how to use Cal.com foreign tables.

Basic example#

This example will create a "foreign table" inside your Postgres database and query its data.

1
create foreign table cal.my_profile (
2
  id bigint,
3
  username text,
4
  email text,
5
  attrs jsonb
6
)
7
  server cal_server
8
  options (
9
    object 'my_profile'
10
  );
11
12
-- query current user used for the Cal.com API request
13
select * from cal.my_profile;

attrs is a special column which stores all the object attributes in JSON format, you can extract any attributes needed from it. See more examples below.

Query JSON attributes#

1
create foreign table cal.bookings (
2
  attrs jsonb
3
)
4
  server cal_server
5
  options (
6
    object 'bookings',
7
    rowid_column 'attrs'
8
  );
9
10
create foreign table cal.event_types (
11
  attrs jsonb
12
)
13
  server cal_server
14
  options (
15
    object 'event-types'
16
  );
17
18
-- extract bookings
19
select
20
  bk->>'id' as id,
21
  bk->>'title' as title,
22
  bk->>'userPrimaryEmail' as email
23
from cal.bookings t
24
  cross join json_array_elements((attrs->'bookings')::json) bk;
25
26
-- extract event types
27
select
28
  etg->'profile'->>'name' as profile,
29
  et->>'id' as id,
30
  et->>'title' as title
31
from cal.event_types t
32
  cross join json_array_elements((attrs->'eventTypeGroups')::json) etg
33
  cross join json_array_elements((etg->'eventTypes')::json) et;

Make a booking#

Once we know an event type ID (we can get it from above example, here we suppose it is 123456), we can make a booking using below SQL.

1
insert into cal.bookings(attrs)
2
values (
3
  '{
4
     "start": "2024-12-12T10:30:00.000Z",
5
     "eventTypeId": 123456,
6
     "attendee": {
7
       "name": "Test Name",
8
       "email": "test.name@example.com",
9
       "timeZone": "America/New_York"
10
     }
11
  }'::jsonb
12
);

To add more details to the booking, such as guests or metadata, refer to Cal.com documentation.