This is the official EdgeDB client library
for JavaScript and TypeScript.
If you're just getting started with EdgeDB, we recommend going through the
EdgeDB Quickstart first. This walks
you through the process of installing EdgeDB, creating a simple schema, and
writing some simple queries.
Migrating to EdgeDB 2.0
We recently released v0.21.0
of the edgedb
module on NPM and deno.land/x,
which supports the latest EdgeDB 2.0 features and protocol. It is
backwards-compatible with v1 instances as well, so we recommend all users
upgrade.
npm install edgedb@latest
Breaking changes
-
All uuid
properties are now decoded to include hyphens. Previously hyphens were elided for performance reasons; this issue has since been resolved.
client.querySingle(`select uuid_generate_v1mc();`);
-
All json
properties and parameters are now parsed/stringified internally by the client. Previously:
const result = await client.querySingle(
`select to_json('{"hello": "world"}');`
);
result;
typeof result;
Now:
const result = await client.querySingle(
`select to_json('{"hello": "world"}');`
);
result;
typeof result;
result.hello;
New features
-
Added the .withGlobals
method to the Client
for setting global variables.
import {createClient} from "edgedb";
const client = createClient().withGlobals({
current_user: getUserIdFromCookie(),
});
client.query(`select User { email } filter .id = global current_user;`);
-
Support for globals in the query builder.
const query = e.select(e.User, user => ({
email: true,
filter: e.op(user.id, "=", e.global.current_user),
}));
await query.run(client);
-
Support for the group statement.
e.group(e.Movie, movie => ({
title: true,
actors: {name: true},
num_actors: e.count(movie.characters),
by: {release_year: movie.release_year},
}));
-
Support for range types and DateDuration
values.
Requirements
- Node.js 12+
- For TypeScript users:
- TypeScript 4.4+ is required
yarn add @types/node --dev
Installation
npm install edgedb
yarn add edgedb
Basic usage
The examples below demonstrate only the most fundamental use cases for this
library. Go to the complete documentation site. >
Create a client
A client is an instance of the Client
class, which maintains a pool of
connections to your database and provides methods for executing queries.
For TypeScript (and Node.js+ESM)
import * as edgedb from "edgedb";
const client = edgedb.createClient();
For Node.js (CommonJS)
const edgedb = require("edgedb");
const client = edgedb.createClient();
Configuring the connection
The call to edgedb.createClient()
doesn't require arguments, as the library
can determine how to connect to your database using the following mechanisms.
-
For local development: initialize a project with the edgedb project init
command. As long as the file is within a project directory, createClient
will be able to auto-discover the connection information of the project's
associated instance. For more information on projects, follow the
Using projects guide.
-
In production: configure the connection using environment variables.
(This can also be used during local development if you prefer.) The easiest
way is to set the EDGEDB_DSN
variable; a DSN (also known as a "connection
string") is a string of the form
edgedb://USERNAME:PASSWORD@HOSTNAME:PORT/DATABASE
.
For advanced cases, see the
DSN specification and
Reference > Connection Parameters.
Run a query
The remainder of the documentation assumes you are using ES module (import
)
syntax.
import * as edgedb from "edgedb";
const client = edgedb.createClient();
await client.query("select 2 + 2");
Note that the result is an array. The .query()
method always returns an
array, regardless of the result cardinality of your query. If your query
returns zero or one elements, use the .querySingle()
instead.
await client.querySingle("select <str>{}");
await client.querySingle("select 2 + 2");
await client.querySingle(
`select Movie { title }
filter .id = <uuid>'2eb3bc76-a014-45dc-af66-2e6e8cc23e7e';`
);
Query builder
Instead of writing queries as strings, you can use this package to generate a
query builder. The query builder lets you write queries in a code-first way
and automatically infers the return type of your queries.
To generate the query builder, install the edgedb
package, initialize a project (if
you haven't already), then run the following command:
$ npx edgeql-js
This will generate an EdgeQL query builder into the ./dbschema/edgeql-js
directory, as defined relative to your project root.
For details on generating the query builder, refer to the complete documentation. Below is a simple
select
query as an example.
import {createClient} from "edgedb";
import e from "./dbschema/edgeql-js";
const client = createClient();
const query = e.select(e.Movie, movie => ({
id: true,
title: true,
actors: {name: true},
num_actors: e.count(movie.actors),
filter: e.op(movie.title, "=", "Dune"),
}));
const result = await query.run(client);
result.actors[0].name;
For details on using the query builder, refer to the full query builder docs.
Contribute
Contributing to this library requires a local installation of EdgeDB. Install
EdgeDB from here or
build it from source.
$ git clone git@github.com:edgedb/edgedb-js.git
$ cd edgedb-js
$ yarn
$ yarn build
$ yarn tests
License
edgedb-js is developed and distributed under the Apache 2.0 license.