dotnet edgeql tool

[quinchs]

Summary

As outlined in #21, this tool provides a way to create .cs files from .edgeql files. All commands/parameters are up for change to meet consistency with other edgedb tools

Commands

Generate

generate is the main command to generate source files from edgeql.

Arguments

  p, project       Whether or not to create the default class library that
                         will contain the generated source code. Enabled by
                         default.

  o, output              The output directory for the generated source to be
                         placed. When generating a project, source files will be
                         placed in that projects directory. Default is the
                         current directory

  n, project-name        The name of the generated project and namespace of
                         generated files.

  f, force               Force regeneration of files

  watch                  Listens for any changes or new edgeql files and
                         (re)generates them automatically

  dsn                    DSN for EdgeDB to connect to (overrides all other
                         options except password)

  credentials-file       Path to JSON file to read credentials from

  I, instance            Local instance name created with edgedb instance create
                         to connect to (overrides host and port)

  H, host                Host of the EdgeDB instance

  P, port                Port to connect to EdgeDB

  d, database            Database name to connect to

  u, user                User name of the EdgeDB user

  password               Ask for password on the terminal (TTY)

  password-from-stdin    Read the password from stdin rather than TTY (useful
                         for scripts)

  tls-ca-file            Certificate to match server against

                         This might either be full self-signed server
                         certificate or certificate authority (CA) certificate
                         that server certificate is signed with.

  tls-security           Specify the client-side TLS security mode.

  loglevel               Configure the log level

  help                   Display more information on a specific command.

  version                Display version information.

Example

> dotnet edgeql generate -o ~/myproject/src/generated

Connection uses the same resolution logic as the edgedb CLI tool, as well as the same arguments for specifying connection parameters.

Watch

The watch command is simply to start/stop/view the watcher for the current project.

Arguments

  k, kill                Kill the current running watcher for the project

  s, start               Start a watcher for the current project

  o, output              The output directory for the generated source to be
                         placed.

  n, project-name        The name of the generated project and namespace of
                         generated files.

  dsn                    DSN for EdgeDB to connect to (overrides all other
                         options except password)

  credentials-file       Path to JSON file to read credentials from

  I, instance            Local instance name created with edgedb instance create
                         to connect to (overrides host and port)

  H, host                Host of the EdgeDB instance

  P, port                Port to connect to EdgeDB

  d, database            Database name to connect to

  u, user                User name of the EdgeDB user

  password               Ask for password on the terminal (TTY)

  password-from-stdin    Read the password from stdin rather than TTY (useful
                         for scripts)

  tls-ca-file            Certificate to match server against

                         This might either be full self-signed server
                         certificate or certificate authority (CA) certificate
                         that server certificate is signed with.

  tls-security           Specify the client-side TLS security mode.

  loglevel               Configure the log level

  help                   Display more information on a specific command.

  version                Display version information.

Example

> dotnet edgeql watch
[10:16:07 INF] No file watcher is running for ~/myproject/

dotnet edgeql watch --start -o ~/myproject/src/generated

Project root is located from the output directory, if none is specified then the current directory + namespace is used.

Generation structure

Code generation will generate a source file per edgeql file, ignoring files in ./dbschema/migrations/*, each generated source file contains a class representing the result and a class containing execute methods. Here's an example:

EdgeQL

select Person {
  name, email
}
filter .email = <str>$email

Source file

// AUTOGENERATED: DO NOT MODIFY
// edgeql:E116C5881529C70BFC6A9D0350075968AD967D391FEE0F74033FA870A1FE56DD
// Generated on 2022-08-26T11:52:03.5962767Z
#nullable enable
using EdgeDB;

namespace EdgeDB.Generated;

#region Types
[EdgeDBType]
public sealed class GetUserResult
{
    [EdgeDBProperty("id")]
    public Guid Id { get; set; }

    [EdgeDBProperty("name")]
    public String? Name { get; set; }

    [EdgeDBProperty("email")]
    public String? Email { get; set; }
}

#endregion

public static class GetUser
{
    public static readonly string Query = @"select Person {
	name, email
}
filter .email = <str>$email";

    public static Task<GetUserResult?> ExecuteAsync(IEdgeDBQueryable client, String? email, CancellationToken token = default)
        => client.QuerySingleAsync<GetUserResult>(Query, new Dictionary<string, object?>() { { "email", email } }, capabilities: (Capabilities)0ul, token: token);

    public static Task<GetUserResult?> GetUserAsync(this IEdgeDBQueryable client, String? email, CancellationToken token = default)
        => ExecuteAsync(client, email, token: token);
}
#nullable restore

A user consuming this generated file has two ways of using it:

// Option one: extension methods
using EdgeDB.Generated;

var client = new EdgeDBClient(...);
var user = await client.GetUserAsync(email: "example@example.com");

...

// Option two: direct call
using EdgeDB.Generated;

var client = new EdgeDBClient(...);
var user = await GetUser.ExecuteAsync(client, email: "example@example.com");

[quinchs]

cc @colinhacks @1st1