aster.Web Data / Docs Aster UI ↗

Aster Web Data / Reference

Command line

The options and exit statuses of the serve, check, update, scaffold and openapi commands.

The server is one program with five modes: serve (the default, which runs the services), check, update, scaffold and openapi. The program is called aster-webdata-server.

serve

With --config, the server serves the configured services until it receives SIGTERM or Ctrl-C.

aster-webdata-server --config server.yaml
aster-webdata-server --config server.yaml --listen 127.0.0.1:9000 --public-url https://api.example.com/shop
aster-webdata-server --config server.yaml --check
Option Meaning
--config FILE, -c FILE The configuration file. Required.
--listen ADDR, -l ADDR Overrides the listen key. Port 0 picks a free port.
--public-url URL Overrides the service's public_url, the root URL clients see. It applies to a configuration with one service. With several services, set public_url in each one instead, and the server refuses the option.
--check Loads the definitions, rules, databases and seeds, opens each database, and exits without serving. A database that cannot open, or fails its check, fails the run.
--help, -h Prints the usage and exits.

On start, the server prints one line on standard output with the address it bound and the service roots. Scripts that start the server can wait for that line.

On the first SIGTERM or Ctrl-C, the server stops accepting requests and lets requests in flight finish, up to shutdown.grace_seconds. A second signal exits at once. See Shutdown behind a load balancer. SIGHUP reloads the configuration and the model without a restart, as Change the model describes.

Exit status

Status Meaning
0 Stopped normally, or --check passed.
1 The server could not start: the address could not be bound, a definition or rule failed to load, or a required database (every database, under --check) could not open or failed its check.
2 Invalid usage or invalid configuration.

check

check reads the configuration and every DataSource. It compares each database's catalog with what the sources declare, and it does not open a connection pool or serve requests.

aster-webdata-server check --config server.yaml

For each source, it prints service.set: database.schema.table. Then it prints one verdict for each database:

Verdict Meaning
databases.<name>: ok The catalog matches the sources.
databases.<name>: N mismatch(es), then one line for each The catalog does not match. Each line says what to change.
databases.<name>: cannot check The database's kind reads no catalog.
databases.<name>: cannot be read: ... The catalog could not be read.

check also prints a warning: line, which does not change the status, for a navigation between sets on two databases over text keys whose collation is not binary. Aster relates those keys by code point, so keys the collation calls equal but whose characters differ do not relate. Give both key columns a binary collation, or keep the sets on one database. A set with no ETag gets a warning too.

Status Meaning
0 Every database passes.
1 A database has a mismatch, or its catalog cannot be read.
2 The configuration is invalid, or the arguments are wrong.

Use check in a deployment pipeline before a release. It needs a connection that can read the catalog of the selected schemas.

update

update installs the latest preview build in place of the running binary. See Preview builds for what a preview build is.

aster-webdata-server update --check
aster-webdata-server update
Option Meaning
--check Prints the installed version and its expiry, and the latest version and its expiry. It changes nothing and exits 0 whether or not a newer build exists.
(none) Downloads the latest build for this platform, checks its signature against the public key built into the server, and replaces the binary. The old binary stays beside it as aster-webdata-server.previous.

update does not restart the server. Restart it yourself to run the new build. It refuses, and changes nothing, in a container (pull the new image instead), when the binary belongs to a package manager, and when the binary's directory is not writable by you. It never asks for elevated rights.

Status Meaning
0 Updated, already up to date, or --check reported.
1 The update was refused or failed. The installed binary is unchanged.
2 Invalid usage.

aster-webdata-server --version prints the version and, for a preview build, its expiry. An expired build still runs --version and update.

scaffold

scaffold writes a starting point for the DataSources of an existing database: one .ds.yaml file for each table or view, and a service.yaml that declares the database and a service named odata listing those files. It reads the database catalog only. It runs no DDL and no SELECT on rows. Review the output before you serve it. The header of each file says that it records how the data is stored, not what it means, and that a schema's foreign keys may be missing or wrong. Notes in each file name what scaffold left out, such as a foreign key whose target is outside the selection. 

aster-webdata-server scaffold --config server.yaml --database shop \
    --schema public --schema billing --include 'orders*' 'customers' 'invoice*' --out model

aster-webdata-server scaffold --kind postgres --url-env SHOP_DATABASE_URL --database shop --schema sales --out model
Option Meaning
--config FILE Uses the database section of this configuration. Give --database NAME when the file has more than one database.
--database NAME The database to read. With --kind, it is the name the generated service uses.
--kind KIND The database kind, when no configuration is given. The kind is read from this option or the configuration, never from a URL.
--url-env VAR The environment variable that holds the connection URL. Use with --kind.
--url-file PATH A file that holds the connection URL. Use with --kind. A file database (DuckDB) takes its path this way.
--schema S A schema to read. Repeatable. Without it, the database's default schema is read.
--include PATTERN ..., --exclude PATTERN ... Table names to keep or drop. Patterns take * and ?. Each flag takes the patterns that follow it, up to the next flag.
--out DIR Writes the files to this directory. Without it, scaffold prints a YAML stream, with the file names in comments.
--force Overwrites files in --out that exist. Without it, scaffold refuses to overwrite.
--help, -h Prints the usage.

A connection URL on the command line is refused, because it would show in the process list and in shell history. Put the URL in an environment variable or a file, and pass --url-env or --url-file. TigerBeetle has a fixed catalog, so there is nothing to scaffold.

Scaffold exits 0 when it writes the files, and 2 on any error.

openapi

openapi writes the OpenAPI 3.1 document of one service to a file, and exits. It does not serve requests.

aster-webdata-server openapi --config server.yaml --service shop --output shop-openapi.json
Option Meaning
--config FILE The configuration file. Required.
--service NAME The service whose document to write. Required when the configuration has several services.
--output FILE The file to write. Default openapi.json.
--language TAG A configured metadata language. Default: the i18n.default language.

The document matches the one served at <root>/openapi.json. Set the service's public_url for a stable server URL in the document. The openapi mode works when the HTTP endpoint is off (openapi: false).

Exit status is 0 on success, 1 on an error such as an unknown service or a file that cannot be written, and 2 for an invalid configuration or arguments.