Meta tags:
description=Lightweight WASM Postgres;

Headings (most frequently used words):

example, objects, options, pglite, extensions, query, transaction, api, about, docs, reference, main, constructor, methods, properties, results, row, tagged, template, queries, dev, blob, framework, hooks, tools, sql, exec, close, listen, unlisten, onnotification, offnotification, dumpdatadir, execprotocol, execprotocolraw, describequery, refresharraytypes, clone, copytofs, ready, closed, waitready, datadir,

Text of the page (most frequently used words):
the (165), #pglite (65), query (53), from (43), test (40), and (35), string (33), sql (29), postgres (28), for (27), name (27), this (27), await (25), promise (25), blob (24), database (22), with (19), options (19), that (19), object (18), you (18), will (17), type (16), can (16), array (16), file (15), select (15), where (15), use (15), when (15), import (14), parameters (14), electric (13), results (13), create (13), types (13), using (12), transaction (12), value (12), void (12), callback (12), extensions (12), method (11), instance (11), live (10), queries (10), data (10), returned (10), any (10), not (10), result (10), number (10), channel (10), dev (9), const (9), example (9), used (9), are (9), each (9), message (9), datadir (9), extension (9), template (8), api (8), returns (8), objects (8), values (8), rows (8), see (8), uint8array (8), protocol (8), copy (7), main (7), datatypeid (7), useful (7), function (7), payload (7), listen (7), pass (6), same (6), only (6), note (6), new (6), wire (6), into (6), storage (6), compression (6), exec (6), module (6), need (5), device (5), support (5), params (5), raw (5), level (5), mapping (5), affectedrows (5), filesystem (5), parser (5), serializer (5), about (5), queryoptions (5), uses (5), all (5), one (5), serializers (5), set (5), parsers (5), wasm (5), memory (5), postgresql (4), has (4), virtual (4), identifier (4), equivalent (4), tag (4), parameter (4), more (4), automatically (4), tagged (4), provided (4), row (4), have (4), waitready (4), ready (4), information (4), client (4), socket (4), execprotocolraw (4), execute (4), passed (4), option (4), close (4), insert (4), start (4), strings (4), ids (4), functions (4), namespace (4), pgliteoptions (4), constructor (4), page (3), started (3), table (3), importing (3), command (3), filterstmt (3), filtervar (3), complex (3), without (3), templating (3), key (3), field (3), fields (3), methods (3), wait (3), closed (3), boolean (3), copytofs (3), mode (3), describequery (3), but (3), would (3), system (3), messages (3), particularly (3), error (3), notification (3), execprotocol (3), returning (3), notifications (3), load (3), which (3), gzip (3), tarball (3), dumpdatadir (3), received (3), subscribe (3), unsubscribe (3), text (3), statement (3), numeric (3), either (3), single (3), plugin (3), process (3), locale (3), initdb (3), instead (3), downloading (3), default (3), version (3), bundler (3), available (3), under (2), getting (2), ret (2), my_table (2), export (2), exporting (2), via (2), require (2), top (2), parametrized (2), passing (2), templated (2), literals (2), allow (2), want (2), like (2), names (2), them (2), prevent (2), there (2), helpers (2), both (2), receive (2), these (2), run (2), time (2), take (2), typescript (2), expected (2), containing (2), count (2), following (2), properties (2), called (2), before (2), fully (2), initialised (2), resolves (2), whether (2), read (2), sets (2), optional (2), filepath (2), current (2), operations (2), clone (2), resultfields (2), queryparams (2), added (2), manually (2), refresharraytypes (2), its (2), convert (2), javascript (2), format (2), build (2), they (2), arrive (2), backend (2), large (2), wrappers (2), transactions (2), alternative (2), your (2), such (2), expose (2), execprotocoloptions (2), other (2), dump (2), back (2), loaddatadir (2), defaults (2), possible (2), environment (2), doesn (2), none (2), auto (2), event (2), handler (2), offnotification (2), onnotification (2), unlisten (2), testing (2), console (2), ensuring (2), return (2), rollback (2), within (2), multi (2), details (2), how (2), literal (2), various (2), also (2), overrides (2), tostring (2), serializeroptions (2), touppercase (2), parseroptions (2), development (2), pgvector (2), vector (2), icu (2), initdbstartparams (2), native (2), startparams (2), pgtype (2), package (2), worker (2), precompiled (2), requires (2), loading (2), esm (2), webassembly (2), connect (2), username (2), user (2), provide (2), filesystems (2), indexeddb (2), debug (2), directory (2), path (2), static (2), sync (2), repl (2), docs (2), navigation (2), dual, licensed, license, apache, next, previous, pager, just, write, myblob, null, additional, configurations, binary, best, order, generate, nested, preserve, behaviour, parametrization, reusable, utilities, avoid, being, interpreted, still, regular, identifiers, column, escape, quotes, becoming, parametrizeable, getname, construct, substituted, converted, calling, directly, validated, cast, describing, shape, written, affected, changed, resolve, necessary, explicitly, longer, accepting, accept, 0o0644, says, encode, textencoder, tmp, txt, copies, clones, series, unit, integration, having, recreate, refresh, columns, contain, enums, update, internal, cache, done, needed, including, get, executing, understanding, structure, inference, describequeryresult, expecting, usage, project, server, onrawdata, execprotocolrawstream, execprotocoloptionsstream, bypasses, manage, notice, listeners, bypass, don, intend, above, features, safer, warning, unparsed, includes, emitted, external, lowest, exposed, interact, existing, clients, likely, something, internally, tcp, gateway, safe, alongside, apis, handles, tuples, consisting, backendmessage, may, compatible, versions, designed, then, combination, starting, dumped, explicit, opt, out, specify, required, suitable, throw, gzipped, remove, does, channel_name, add, removes, subscription, unsubscribes, callbacks, case, sensitive, double, quoted, otherwise, lower, cased, notify, hello, world, log, unsub, pg_notify, shut, down, cleanly, async, committed, rolled, rejected, interactive, perform, serial, primary, exists, simple, applying, migrations, running, statements, supported, section, along, cases, templatestringsarray, attach, bigint, 100, mappings, positional, fieldname, rowmode, extended, optionally, develop, parings, included, loaded, include, official, documentation, conf, postgresqlconf, provider, exe, application_name, awesome, defaultstartparams, convenience, exports, constant, most, common, bundle, restricted, edge, fsbundle, initdbwasmmodule, pglitewasmmodule, initial, amount, bytes, allocate, grow, higher, pause, during, growth, initialmemory, cluster, permissions, applied, context, wish, starts, should, produced, related, providing, prefix, initialise, yourself, here, relaxed, durability, flushes, complete, after, relaxeddurability, logs, sent, store, first, argument, ephemeral, platforms, browser, idb, unprefixed, node, bun, storing, uri, scheme, backends, created, standard, due, typesscript, limitations, awaits, been, couple, advantages, preferred, way, resolving, imported, debugging, benchmarks, examples, reference, catalog, upgrade, prepopulated, pgdump, tools, orms, builders, component, tab, vue, react, framework, hooks, videos, what, sidebar, menu, npm, github, home, search, skip, content,

Text of the page (random words):
ons will be applied in the context of this user database string the database from the postgres cluster within the datadir to connect to initialmemory number the initial amount of memory in bytes to allocate for the pglite instance pglite will grow the memory automatically but if you have a particularly large database you can set this higher to prevent the pause during memory growth pglitewasmmodule webassembly module a precompiled pglite wasm module to use instead of downloading the default version or when using a bundler that either can or requires loading the wasm module with a esm import initdbwasmmodule webassembly module a precompiled initdb wasm module to use instead of downloading the default version or when using a bundler that either can or requires loading the wasm module with a esm import fsbundle blob file a filesystem bundle to use instead of downloading the default version this is useful if in a restricted environment such as an edge worker parsers parseroptions an object of type pgtype number value string any mapping postgres data type ids to parser functions for convenience the pglite package exports a constant for most common postgres types ts import pglite types from electric sql pglite const pg await pglite create parsers types text value value touppercase serializers serializeroptions an object of type pgtype number value any string mapping postgres data type ids to serializer functions ts import pglite types from electric sql pglite const pg await pglite create serializers types numeric value value tostring startparams string an array of strings that will be passed to the postgres process as start parameters this is the set of parameters one would pass to a native postgresql instance ts import pglite from electric sql pglite const pg await pglite create startparams pglite defaultstartparams c application_name my awesome backend initdbstartparams string an array of strings that will be passed to the initdb process as start parameters this is the set of parameters one would pass to a native initdb exe ts import pglite from electric sql pglite const pg await pglite create initdbstartparams locale provider icu icu locale de postgresqlconf string string a postgresql conf file as an array of strings or a single string you can use it to pass parameters to the postgresql process see official documentation for details options extensions pglite and postgres extensions are loaded into a pglite instance on start and can include both a wasm build of a postgres extension and or a pglite client plugin the options extensions parameter is an object of namespace extension parings the namespace is used to expose the pglite client plugin included in the extension an example of this is the live queries extension ts import pglite from electric sql pglite import live from electric sql pglite live import vector from electric sql pglite pgvector const pg await pglite create extensions live live query extension is a pglite client plugin vector postgres pgvector extension the live namespace is added by the use of the live key in the extensions object pg live query for information on how to develop a pglite extension see extension development methods query query t query string params any options queryoptions promise results t execute a single statement optionally with parameters uses the extended query postgres wire protocol returns single result object example ts await pg query insert into test name values 1 test affectedrows 1 query options the query and exec methods take an optional options objects with the following parameters rowmode object array the returned row object type either an object of fieldname value mappings or an array of positional values defaults to object parsers parseroptions an object mapping postgres data type ids to parser functions this option overrides any parsers set at the instance level ts import types from electric sql pglite await pg query select from test where name 1 test parsers types text value value touppercase serializers serializeroptions an object mapping postgres data type ids to serializer functions this option overrides any serializers set at the instance level ts import types from electric sql pglite await pg query insert into test numeric values 1 100 n serializers types numeric value number bigint value tostring blob blob file attach a blob or file object to the query that can used with a copy from command by using the virtual dev blob device see importing and exporting sql sql t promise results t sql t strings templatestringsarray params any promise results t you can also use the sql tagged template literal to create queries ts await pg sql select from test where name test equivalent of pg query select from test where name 1 test see the templating section for more details on how to use the tagged template literal along with various helpers for more complex cases exec exec query string options queryoptions promise array results execute one or more statements note that parameters are not supported this is useful for applying database migrations or running multi statement sql that doesn t use parameters uses the simple query postgres wire protocol returns array of result objects one for each statement example ts await pg exec create table if not exists test id serial primary key name text insert into test name values test select from test affectedrows 0 affectedrows 1 rows id 1 name test affectedrows 0 fields name id datatypeid 23 name name datatypeid 25 transaction transaction t callback tx transaction promise t to start an interactive transaction pass a callback to the transaction method it is passed a transaction object which can be used to perform operations within the transaction the transaction will be committed when the promise returned from your callback resolves and automatically rolled back if the promise is rejected transaction objects tx query t query string params any options queryoptions promise results t the same as the main query method tx sql t promise results t the same as the main sql template string method tx exec query string options queryoptions promise array results the same as the main exec method tx rollback rollback and close the current transaction example ts await pg transaction async tx await tx query insert into test name values 1 test return await ts query select from test close close promise void close the database ensuring it is shut down cleanly listen listen channel string callback payload string void promise promise void subscribe to a pg_notify channel the callback will receive the payload from the notification returns an unsubscribe function to unsubscribe from the channel example ts const unsub await pg listen test payload console log received payload await pg query notify test hello world channel names are case sensitive if double quoted pg listen test otherwise channel name will be lower cased pg listen testing pg listen testing unlisten unlisten channel string callback payload string void promise void unsubscribe from the channel if a callback is provided it removes only that callback from the subscription when no callback is provided it unsubscribes all callbacks for the channel onnotification onnotification callback channel string payload string void void add an event handler for all notifications received from postgres note this does not subscribe to the notification you will need to manually subscribe with listen channel_name offnotification offnotification callback channel string payload string void void remove an event handler for all notifications received from postgres dumpdatadir dumpdatadir compression auto gzip none promise file blob dump the postgres datadir to a gzipped tarball the compression option defaults to auto which uses compression where possible you can explicit opt in or out of compression with gzip and none when you specify that compression is required with gzip if the environment doesn t support a suitable compression api it will throw an error this can then be used in combination with the loaddatadir option when starting pglite to load a dumped database from storage note the datadir dump may not be compatible with other postgres versions it is only designed for importing back into pglite execprotocol execprotocol message uint8array options execprotocoloptions promise array backendmessage uint8array execute a postgres wire protocol message returning an array of tuples one for each wire protocol result message consisting of the passed message object see pg protocol the raw uint8array for that message this api is safe to use alongside the other pglite query apis as it handles error transactions and notifications execprotocolraw execprotocolraw message uint8array options execprotocoloptions promise uint8array execute a postgres wire protocol message returning the unparsed result uint8array this includes all wire protocol result messages emitted as a result of your message and will require external passing this is the lowest level api exposed by pglite and can be used to interact with a pglite database using existing postgres clients it is likely that you will want to use something such as pg gateway that uses this internally to expose the database on a tcp socket warning execprotocolraw bypasses pglite s protocol wrappers that manage error notice messages transactions and notification listeners only use if you need to bypass these wrappers and don t intend to use the above features execprotocol is a safer alternative execprotocolrawstream message uint8array options execprotocoloptionsstream void same as execprotocolraw but returns raw messages in the options onrawdata callback as they arrive from the backend this is particularly useful when expecting large sets of data see a usage example in the pglite socket project where the server uses this method to pass the results to the client socket as they arrive describequery describequery query string options queryoptions promise describequeryresult get type information about a query s parameters and result fields without executing it this is useful for understanding the expected parameter types and the structure of the results that would be returned it can be used to build a type inference system for queries using pglite returns an object with queryparams array datatypeid number serializer function information about each parameter s postgres type id and the serializer function used to convert javascript values to postgres format resultfields array name string datatypeid number parser function information about each result field including its name postgres type id and the parser function used to convert postgres values to javascript format refresharraytypes refresharraytypes promise void refresh the array types in the database this is useful when you have added columns that contain array types ie array of enums and need to update the internal array type cache this is done automatically when the database is started but can be called manually if needed example ts await pg describequery select from test where name 1 test returns queryparams datatypeid 25 serializer function resultfields name id datatypeid 23 parser function clone clone promise pglite clones the current instance this is useful when a series of operations like unit or integration test need to be run on the same database without having to recreate the database each time or for each test copytofs copytofs filepath string data uint8array mode number copies the data to a file at filepath in the virtual filesystem and sets the optional mode of the file example ts await pg copytofs tmp test txt new textencoder encode pglite says hi 0o0644 properties ready ready boolean read only whether the database is ready to accept queries closed closed boolean read only whether the database is closed and no longer accepting queries waitready waitready promise void promise that resolves when the database is ready to use note query methods will wait for the waitready promise to resolve if called before the database has fully initialised and so it is not necessary to wait for it explicitly results t objects result objects have the following properties rows row t the rows returned by the query affectedrows number count of the rows affected by the query note this is not the count of rows returned it is the number or rows in the database changed by the query fields name string datatypeid number field name and postgres data type id for each field returned blob blob a blob containing the data written to the virtual dev blob device by a copy to command see dev blob row t objects rows objects are a key value mapping for each row returned by the query the query t method can take a typescript type describing the expected shape of the returned rows note these types are not validated at run time the result is only cast to the provided type tagged template queries pglite has support for using tagged template literals to construct sql queries via the sql method on both the main pglite instance and transaction objects substituted template values are automatically converted to query parameters and you receive the same results as calling the query api directly ts const name getname await pg sql select from test where name name there are helpers in the template export to create more complex and parametrizeable templated queries identifier tag identifiers like column and table names to escape them with quotes and prevent them from becoming parameters raw tag any string that you want to avoid being interpreted as a parameter will allow you to still do regular string templating sql tag nested templated literals to preserve behaviour and parametrization will allow you to create reusable templating utilities query use at the top level tag in order to generate the parametrized query without passing it to the query api returns a query string params any object with the parametrized query and any parameters used in the query if you require additional configurations or complex binary parameters it s best to use the query method example ts import identifier raw sql query from electric sql pglite template await pg sql select from identifier test where name test equivalent of pg query select from test where name 1 test const filterstmt filtervar string filtervar sql where name filtervar raw where 1 1 await pg sql select from test filterstmt test equivalent of pg query select from test where name 1 test await pg sql select from test filterstmt null equivalent of pg query select from test where 1 1 query select from identifier test where name test query select from test where name 1 params test dev blob pglite has support for importing and exporting via the sql copy to from command by using a virtual dev blob device to import a file pass the file or blob in the query options as blob and copy from the dev blob device ts await pg query copy my_table from dev blob blob myblob to export a table or query to a file you just need to write to the dev blob device the ...