Prostgles

Configuration options

dbConnection required DbConnection

Database connection details and options
onReady required OnReadyCallback

Called when the prostgles server is ready to accept connections. It waits for auth, tableConfig and other async configurations to complete before executing
tsGeneratedTypesDir optional string

Path to the directory where the generated types (DBGeneratedSchema.d.ts) will be saved. This file exports a DBGeneratedSchema type which contains types for the database tables and can be used as a generic type input for the prostgles instances to ensure type safety
io optional Server<DefaultEventsMap, DefaultEventsMap, DefaultEventsMap, any> | undefined

Socket.IO server instance object required to allow clients to connect through websockets

restApi optional RestApiConfig

Rest API configuration. The REST API allows interacting with the database similarly to the websocket connection. with the exception of subscriptions and realtime features.

POST Routes:

/api/db/:tableName/:command
/api/db/sql
/api/methods/:method
/api/schema

Example request:


const res = await fetch(
 `http://127.0.0.1:3001/api/db/items/findOne`,
 {
   method: "POST",
   headers: new Headers({
     'Authorization': `Bearer ${Buffer.from(token, "utf-8").toString("base64")}`,
     'Accept': 'application/json',
     'Content-Type': 'application/json'
   }),
   body: JSON.stringify([{ id: 1 }]),
 }
);

disableRealtime optional boolean | undefined

If true then schema watch, subscriptions and syncs will be disabled. No prostgles schema will be created which is needed for the realtime features. This is useful when you want to connect to a database and prevent any changes to the schema
publish optional Publish

Data access rules applied to clients. By default, nothing is allowed.
publishRawSQL optional (params: PublishParams<S, SUser>) => Awaitable<boolean | ”*”>

If defined and resolves to true then the connected client can run SQL queries
publishMethods optional PublishMethods<S, SUser> | PublishMethodsV2<S, SUser> | undefined

Server-side functions that can be invoked by the client
testRulesOnConnect optional boolean | undefined

If true then will test all table methods on each socket connect. Not recommended for production
joins optional Joins

Allows defining table relationships that can then be used in filters and data inserts:
- infered - uses the foreign keys to infer the joins
- Join[] - specifies the joins manually
schemaFilter optional Record<string, 1> | Record<string, 0> | undefined

If defined then the specified schemas are included/excluded from the prostgles schema. By default only current_schema() is included.
sqlFilePath optional string

Path to a SQL file that will be executed on startup (but before onReady).
transactions optional boolean | undefined

If true then will allow transactions on the server through the db.tx method:
```
 db.tx(async t => {
   await t.items.insert({ name: "a" });
   throw new Error("rollback");
 })
```
onSocketConnect optional (args: AuthRequestParams<S, SUser> & { socket: PRGLIOSocket; }) => void | Promise<void>

Called when a socket connects Use for connection verification. Will disconnect socket on any errors
onSocketDisconnect optional (args: AuthRequestParams<S, SUser> & { socket: PRGLIOSocket; }) => void | Promise<void>

Called when a socket disconnects
auth optional AuthConfig

Auth configuration. Supports email and OAuth strategies
DEBUG_MODE optional boolean | undefined

Used internally for debugging
onQuery optional (error: any, ctx: IEventContext<IClient>) => void

Callback called when a query is executed. Useful for logging or debugging
onConnectionError optional (error: Error, ctx: IEventContext<IClient>) => void

Called when a connection error is received from the database
watchSchemaType optional “DDL_trigger” | “prostgles_queries” | undefined

What schema change watcher to use when watchSchema is enabled:
- "DDL_trigger" - (default) - Use a database event trigger for schema changes. Requires superuser.
- "prostgles_queries" - Check db.sql() initiated queries for schema changes. Any other queries are ignored.
watchSchema optional boolean | EventTriggerTagFilter | “hotReloadMode” | OnSchemaChangeCallback | undefined

Reloads schema on schema change. Either calls the provided callback or triggers “onReady” on both the server and any connected clients when schema changes and also updates DBGeneratedSchema.d.ts if enabled. Options:
- true - “onReady” call and “DBGeneratedSchema” rewrite
- EventTriggerTagFilter - same as true but only on specified events
- "hotReloadMode" - only rewrites DBGeneratedSchema.d.ts. Used in development when server restarts on file change.
- OnSchemaChangeCallback - custom callback to be fired. Nothing else triggered Useful for development
onNotice optional (notice: AnyObject, message?: string | undefined) => void

Called when a notice is received from the database
fileTable optional FileTableConfig

Enables file storage and serving. Currently supports saving files locally or to AWS S3. By designating a file table files can be inserted through the table handler:
```
const file = await db.files.insert(
   { file: new Buffer("file content"), name: "file.txt" },
   { returnType: "*" }
);
 
const fileUrl = file.url;
```
tableConfig optional TableConfig

Define tables through a JSON-schema like object. Allows adding runtime JSONB validation and type safety. Should be used with caution because it tends to revert any changes made to the database schema through SQL queries
tableConfigMigrations optional TableConfigMigrations

Migration logic used when the new tableConfig version is higher than the one in the database. By default server will fail to start if the tableConfig schema changes cannot be applied without errors
- silentFail optional boolean | undefined
  
  If false then prostgles won’t start on any tableConfig error true by default
- versionTableName optional string
  
  Table that will contain the schema version number and the tableConfig Defaults to schema_version
- version required number
  
  Current schema version number. Must increase on each schema change.
- onMigrate required OnMigrate
  
  Script executed before tableConfig is loaded and IF an older schema_version is present. Any data conflicting with the new schema changes should be resolved here.
onLog optional (evt: EventInfo) => void | Promise<void>

Usefull for logging or debugging