Configuration

This guide explains how to configure @pdftron/collab-sql-resolver-generator in order to generate your resolvers.

Database type (required)#

The resolver generator needs to know which kind of database you are using. You can provide this data via the client option. This option is required.

import SQLResolverGenerator, { SQLClient } from '@pdftron/collab-sql-resolver-generator';

const resolvers = SQLResolverGenerator({
  client: SQLClient.MySQL,
  ...otherOptions
})

The possible values are as follows:

mysql (MySQL)
pg (PostgreSQL)
sqlite3 (SQLite)
oracledb (Oracle)
mssql (Microsoft SQL)

Database connection (required)#

The resolver generator also needs to know how to connect to your database in order to make read/writes. You can provide this information via the connection option. This option is required.

This option can accept a number of different data types:

1) Connection object

You can provide connection details manually, like so:

import SQLResolverGenerator from '@pdftron/collab-sql-resolver-generator';

const resolvers = SQLResolverGenerator({
  connection: {
    host: '127.0.0.1',
    user: 'username',
    password: 'password123',
    database: 'pdftron_collab'
  },
  ...otherOptions
})

The connection object accepts the following data (all optional):

host (string) The hostname for your database. This can also be an entire connection string.
user (string) The username to use when connecting to your database
password (string) The password to use
database (string) The name of the database
filename (string) A filename for an SQLite3 adapter. See this guide for more info.
socketPath (string) Connect via unix domain socket. See this guide for more info.

2) Knex connection objects

This module uses Knex.js under the hood. This means that we can accept the same connection configuration that Knex accepts.

See this guide for info on what can be passed.

Database info (required)#

In order to generate queries, we need to know the names of your tables and the names of the columns that are relevant to collaboration.

This information can be passed via the info parameter.

The info object must contain 6 objects: Users, Annotations, Documents, AnnotationMembers, DocumentMembers, and Mentions. Each of these objects contains information on how to read/write data for the corresponding entity.

If you are using the snapshots feature, an additional 2 objects are required - Snapshots and SnapshotAssets.

important

For the purpose of these guides, we are going to call each of these objects table entities

import SQLResolverGenerator from '@pdftron/collab-sql-resolver-generator';

const resolvers = SQLResolverGenerator({
  ...otherOptions,
  info: {
    Users: {}, // info on how to read/write users
    Annotations: {}, // info on how to read/write annotations
    Documents: {}, // etc
    AnnotationMembers: {},
    DocumentMembers: {},
    Mentions: {},

    // These two are only required if using the snapshots feature.
    Snapshots: {},
    SnapshotAssets: {}
  }
})

Table entities#

Each table entity should provide information on how to read/write data for that kind of entity. This includes the name of the table to query, the names of your columns, and any other additional transforms.

Each table entity should contain the following information:

table (string - required) The name of the table to query
columns (ColumnMap - required) Information about the columns to query. More info below
middleware (Function[]) Additional transforms to apply to queries. More info here

For example, if you provide the following:

import SQLResolverGenerator from '@pdftron/collab-sql-resolver-generator';

const resolvers = SQLResolverGenerator({
  ...otherOptions,
  info: {
    Users: {
      table: 'customers', // the name of your table
      columns: { ...columnInfo },
    },
    ...otherTableEntities
  }
})

Whenever we need to get information about a user, we will generate a query that looks like this:

SELECT * FROM customers WHERE ...

Column maps#

A column map is an object that contains information about the columns in the corresponding table. Each table entity requires different column information to be provided.

The names of these columns will be used when generating SQL queries.

Let's start by showing an example:

import SQLResolverGenerator from '@pdftron/collab-sql-resolver-generator';

const resolvers = SQLResolverGenerator({
  info: {
    Users: {
      table: 'customers', // the name of your table
      columns: {
        id: 'id',
        email: 'customer_email',

        // An object with a 'name' property can also be passed
        userName: { name: 'customer_username' },
        ...other
      },
    },
  }
})

Each key in columns represents a piece of data that we require, and each value represents which column in your database that data lives in.

So, for the above codeblock, if we need to get a user from their email, we would generate this query:

SELECT * FROM customers WHERE customer_email = 'test@test.com'

note

An object with a name property can also be passed as well. This is useful when providing other column level options, such as transforms or joins.

const resolvers = SQLResolverGenerator({
  info: {
    Users: {
      table: 'customers',
      columns: {
        // These two have identical functionality
        id: 'Id',
        id: { name: 'Id' },
      },
    },
  }
})

All of the required information is documented below

All required column maps#

User column map

The user column map requires the following properties:

id
type
email
userName (optional)
createdAt
updatedAt

Example:

import SQLResolverGenerator from '@pdftron/collab-sql-resolver-generator';

const resolvers = SQLResolverGenerator({
  info: {
    Users: {
      table: 'customers',
      columns: {
        id: 'Id',
        // An object with a 'name' property can also be passed
        userName: { name: 'customer_username' },
        type: { name: 'Type' },
        email: 'Email',
        userName: 'UserName',
        createdAt: 'CreatedAt',
        updatedAt: 'DeletedAt',
      },
    },
  }
})

Annotation column map

The annotation column map requires the following properties:

id
xfdf
authorId
annotationId
documentId
pageNumber
createdAt
updatedAt
inReplyTo
annotContents (optional)

Example:

import SQLResolverGenerator from '@pdftron/collab-sql-resolver-generator';

const resolvers = SQLResolverGenerator({
  info: {
    Annotations: {
      table: 'Annotations',
      columns: {
        id: 'Id',
        xfdf: 'Xfdf',
        authorId: 'CreatedBy',
        annotationId: 'AnnotationId',
        documentId: 'DocId',
        pageNumber: 'PageNumber',
        createdAt: 'CreatedAt',
        updatedAt: 'UpdatedAt',
        inReplyTo: 'InReplyTo',
        annotContents: 'Contents',
      },
    },
  }
})

Document column map

The document column map requires the following properties:

id
authorId
createdAt
updatedAt
isPublic
name (optional)

Example:

import SQLResolverGenerator from '@pdftron/collab-sql-resolver-generator';

const resolvers = SQLResolverGenerator({
  info: {
    Documents: {
      table: 'Documents',
      columns: {
        id: 'Id',
        authorId: 'CreatedBy',
        createdAt: 'CreatedAt',
        updatedAt: 'UpdatedAt',
        isPublic: 'IsPublic',
        name: 'Name',
      },
    },
  }
})

Annotation Member column map

The annotation members column map requires the following properties:

id
userId
documentId
annotationId
lastRead
createdAt
updatedAt
annotationCreatedAt

Example:

import SQLResolverGenerator from '@pdftron/collab-sql-resolver-generator';

const resolvers = SQLResolverGenerator({
  info: {
    AnnotationMembers: {
      table: 'AnnotationMembers',
      columns: {
        id: 'Id',
        userId: 'CreatedBy',
        documentId: 'DocId',
        annotationId: 'AnnotId',
        lastRead: 'LastRead',
        createdAt: 'CreatedAt',
        updatedAt: 'UpdatedAt',
        annotationCreatedAt: 'AnnotCreatedAt',
      },
    },
  }
})

Document Member column map

The document members column map requires the following properties:

id
userId
documentId
lastRead
createdAt
updatedAt

Example:

import SQLResolverGenerator from '@pdftron/collab-sql-resolver-generator';

const resolvers = SQLResolverGenerator({
  info: {
    DocumentMembers: {
      table: 'DocumentMembers',
      columns: {
        id: 'Id',
        userId: 'CreatedBy',
        documentId: 'DocId',
        lastRead: 'LastRead',
        createdAt: 'CreatedAt',
        updatedAt: 'UpdatedAt',
      },
    },
  }
})

Mentions column map

The mentions column map requires the following properties:

id
userId
documentId
annotationId
createdAt
updatedAt

Example:

import SQLResolverGenerator from '@pdftron/collab-sql-resolver-generator';

const resolvers = SQLResolverGenerator({
  info: {
    Mentions: {
      table: 'Mentions',
      columns: {
        id: 'Id',
        userId: 'UserId',
        documentId: 'DocId',
        annotationId: 'AnnotId',
        createdAt: 'CreatedAt',
        updatedAt: 'UpdatedAt',
      },
    },
  }
})

Snapshots column map (optional)

This is only required if using the snapshot feature.

The snapshots column map requires the following properties:

id
authorId
documentId
xfdf
name
createdAt
updatedAt

Example:

import SQLResolverGenerator from '@pdftron/collab-sql-resolver-generator';

const resolvers = SQLResolverGenerator({
  info: {
    Snapshots: {
      table: 'Snapshots',
      columns: {
        id: 'Id',
        authorId: 'AuthorId',
        documentId: 'DocumentId',
        xfdf: 'Xfdf',
        name: 'Name',
        createdAt: 'CreatedAt',
        updatedAt: 'UpdatedAt',
      },
    },
  }
})

SnapshotAssets column map (optional)

This is only required if using the snapshot feature.

The snapshot assets column map requires the following properties:

id
snapshotId
data
createdAt
updatedAt

import SQLResolverGenerator from '@pdftron/collab-sql-resolver-generator';

const resolvers = SQLResolverGenerator({
  info: {
    SnapshotAssets: {
      table: 'SnapshotAssets',
      columns: {
        id: 'Id',
        snapshotId: 'SnapshotId',
        data: 'Data',
        createdAt: 'CreatedAt',
        updatedAt: 'UpdatedAt',
      },
    },
  }
})

Database type (required)#

Database connection (required)#

Database info (required)#

important

Table entities#

Column maps#

note

All required column maps#

Next steps#