Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Extension API #99

Merged
merged 1 commit into from
Jun 25, 2024
Merged

Extension API #99

merged 1 commit into from
Jun 25, 2024

Conversation

samwillis
Copy link
Collaborator

@samwillis samwillis commented Jun 18, 2024

Stacked on #102

The extensions API provides the place to initiate Postgres extensions or plugins:

import { PGlite } from '@electric-sql/pglite'
import { vector } from '@electric-sql/pglite-pgvector'
import { postgis } from '@electric-sql/pglite-postgis'

const db = new PGlite({
  path: 'idb://my-db',
  extensions: {
    vector,
    postgis,
  }
})

plugins would have the interface:

export interface ExtensionSetupResult {
emscriptenOpts?: any;
namespaceObj?: any;
init?: () => Promise<void>;
close?: () => Promise<void>;
}
export type ExtensionSetup = (
pg: PGliteInterface,
emscriptenOpts: any,
) => Promise<ExtensionSetupResult>;
export interface Extension {
name?: string;
setup: ExtensionSetup;
}
export type Extensions = {
[namespace: string]: Extension;
};

setup will be called after the runtime is ready, but before starting PG, and would be passed the Emscripten module mod and the PGlite instance pg:

  • Via pg they can call any PGlite apis
  • Via emscriptenOpts they can include additional files in the VFS

init will be called after starting PG, but before the instance is marked as ready to receive calls.
namespaceObj is an object to include on the main PGlite instance, this can be used to expose additional methods provided by the extension.

In order for the typescript type to be correctly added to the PGlite instance you can call the PGlite.withExtensions() factory function, this would ensure all the namespace added by the extension is known to typescript. (there is no way to do this on the standard constructor)

import { PGlite } from '@electric-sql/pglite'
import { vector } from '@electric-sql/pglite-pgvector'
import { postGIS } from '@electric-sql/pglite-postgis'

const db = PGlite.withExtensions({
  path: 'idb://my-db',
  extensions: {
    vector,
    postGIS,
    customNamespace: myExtension,
  }
})

// TS awair of
db.customNamespace.myMethod()

An example of a first extension (js only) is the live query plugin: #104

@samwillis samwillis force-pushed the samwillis/extension-api branch from 0f5ae1a to 9c31154 Compare June 21, 2024 10:33
@samwillis samwillis changed the base branch from main to samwillis/pg_notify June 21, 2024 10:34
@samwillis samwillis mentioned this pull request Jun 21, 2024
2 tasks
@samwillis samwillis force-pushed the samwillis/extension-api branch from b8668a1 to 5c9ec28 Compare June 21, 2024 13:05
@samwillis samwillis force-pushed the samwillis/pg_notify branch from e3df5b4 to be9a223 Compare June 21, 2024 13:08
@samwillis samwillis force-pushed the samwillis/extension-api branch from 5c9ec28 to c0f5766 Compare June 21, 2024 13:10
@samwillis samwillis changed the title WIP Extension API Extension API Jun 23, 2024
@samwillis samwillis marked this pull request as ready for review June 23, 2024 20:11
@samwillis samwillis force-pushed the samwillis/pg_notify branch from be9a223 to d288157 Compare June 25, 2024 20:58
More extension api

Tweak extension api

Remove test code
@samwillis samwillis force-pushed the samwillis/extension-api branch from db0bd3e to 0523b6d Compare June 25, 2024 21:31
@samwillis samwillis changed the base branch from samwillis/pg_notify to main June 25, 2024 21:31
@samwillis samwillis merged commit 188a524 into main Jun 25, 2024
@samwillis samwillis deleted the samwillis/extension-api branch August 1, 2024 11:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant