Quickstart

Let’s get started with Recap.

1. Install Recap
2. Add a Connection
3. Read a Schema
4. Start Recap’s Server
5. Next Steps

Install Recap

Start by installing Recap:

pip install 'recap-core[all]'

The [all] part will install all of Recap’s dependencies, including the optional ones for systems like PostgreSQL, Snowflake, BigQuery, and so on. You might not need all of these dependencies, but they’ll be available anyway.

Add a Connection

You can use Recap’s command line interface (CLI) to add systems for Recap to connect to. If you’ve got a PostgreSQL database running locally, you can add it to Recap like this:

recap add my_pg postgresql://user:pass@host:port/dbname

This will add a system called my_pg to Recap.

Recap “systems” are just named connections to external systems. They’re not the same as the systems themselves. Recap doesn’t store any data from external systems. It just connects to them in realtime to fetch schemas.

Read a Schema

Now that you’ve got a PostgreSQL database added, we can browse its structure.

recap ls

[
  "my_pg"
]

The ls command lists a path in Recap. Since we haven’t supplied a path, it’s listing systems. Let’s keep drilling down:

recap ls my_pg

[
  "postgres",
  "template0",
  "template1",
  "testdb"
]

You can see the databases inside my PostgreSQL system. Recap models Postgres paths as [system]/[database]/[schema]/[table], so the the testdb database is my_pg/testdb.

Browse around a bit to get a feel for how things are structured. Eventually, you’ll find a path to a table. In my database, I’ve got my_pg/testdb/public/test_types. Let’s read the schema:

recap schema my_pg/testdb/public/test_types

{
  "type": "struct",
  "fields": [
    {
      "type": "int64",
      "name": "test_bigint",
      "optional": true
    }
  ]
}

This is test_type’s schema represented as a Recap schema in JSON. The schema command reads a schema at the supplied path, converts it to a Recap schema, and prints the Recap schema as a JSON object.

Start Recap’s Server

We’ve been using Recap’s CLI to read schemas, but Recap comes with an gateway server as well. The gateway server can list and read schemas over HTTP/JSON. You will find this handy if you’re not using Python, or if you want to integrate Recap with other systems.

Start the server at http://localhost:8000:

recap serve

The server exposes /ls and /schema endpoints that are very similar to the CLI. I’ve already added a my_pg system in the CLI section above, so I can list the system in my Recap gateway:

$ curl http://localhost:8000/ls/my_pg

["postgres","template0","template1","testdb"]

And much like the CLI, I can read my test_types schema:

curl http://localhost:8000/schema/my_pg/testdb/public/test_types

{"type":"struct","fields":[{"type":"int64","name":"test_bigint","optional":true}]}

Recap’s HTTP/JSON gateway does not require a database or any persistence. It just connects to external systems in realtime to fetch schemas.

Next Steps

You’ve learned how to install Recap, connect it to a PostgreSQL database, read schemas, and start Recap’s gateway server.

Next, you should look at Recap’s integrations page to learn how to use Recap with other systems. If you’re planning on running Recap’s gateway, check out its configuration options in the gateway documentation. Finally, see Recap’s API documentation to learn how to use Recap’s Python API.