Qubit Docs العربية

PostgreSQL

Connect a PostgreSQL database so Qubit can read the tables in one schema. You can copy the data into Qubit on a schedule (Sync Mode) or query the database live (Direct Mode).

Before you start

  • Create a dedicated read-only user for Qubit and grant it SELECT on the tables you want to use, plus USAGE on their schema.
  • Make sure the database accepts connections from Qubit's servers. If it is only reachable inside a private network, you can connect through an SSH bastion host (see below).
  • Know which schema holds your tables. PostgreSQL uses public by default.

Connect PostgreSQL

  1. Open Data Catalog from the sidebar, click Add Data, then choose Connect a database.
  2. On the New Data Source page, click PostgreSQL. It is under Databases.
  3. Enter a Connection Name.
  4. Fill in the connection details:
    • Host or connection URI: the server's hostname or IP address. You can also paste a full URI such as postgresql://user:[email protected]:5432/app. Qubit then fills in the port, database, username, and password for you, and reads schema and sslmode from the URI if present.
    • Port: defaults to 5432.
    • Database: the database name.
    • Username and Password: the read-only user you created.
    • Schema: the schema to read. Defaults to public.
  5. Under Connection Mode, choose Sync Mode to copy the data into Qubit, or Direct Mode to query the database live without copying it.
  6. To reach the database through a bastion host, turn on Connect via SSH tunnel and enter the SSH host, SSH port, SSH username, SSH private key (PEM), and the key passphrase if it has one. The tunnel always uses Direct Mode.
  7. For Sync Mode, choose a Sync Schedule. The default is Daily.
  8. Click Create.

Qubit tests the connection before saving it. When the test passes, Qubit saves the connection and takes you to the Data Catalog. In Sync Mode, the first sync starts right away.

If the test fails

The form shows the error message and highlights the field to check:

  • "Authentication failed": the username or password is wrong.
  • "Host could not be resolved": check the hostname spelling.
  • "Could not reach" or "timed out": check the host and port, and that the database accepts remote connections from Qubit.
  • "Database does not exist": check the database name.
  • "Schema does not exist": check the schema name. Data is often loaded into a schema named after the database.

If the connection works but no tables appear, or Test connection reports 0 tables, check that you picked the right schema and that the user can read its tables.