> ## Documentation Index
> Fetch the complete documentation index at: https://sequinstream.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create database

> Create a new Postgres database connection with a replication slot.

### Request body

<Note>
  For creates, the `replication_slots` array must exist and contain exactly one replication slot object.
</Note>

<ParamField body="name" type="string" required>
  A name for this database connection. You can use this name to identify the database across the API.
</ParamField>

<ParamField body="url" type="string">
  The full connection URL for the database, e.g. `postgresql://postgres:secret-password@db.example.com:5432/postgres`.

  Pass in either this parameter or `database`, `hostname`, `port`, `username`, `password`.

  To specify SSL, use the separate `ssl` field.
</ParamField>

<ParamField body="hostname" type="string" required>
  The database server hostname.
</ParamField>

<ParamField body="database" type="string" required>
  The name of the logical database in Postgres.
</ParamField>

<ParamField body="username" type="string" required>
  The database username.
</ParamField>

<ParamField body="password" type="string" required>
  The database password.
</ParamField>

<ParamField body="port" type="integer">
  The database server port. Defaults to `5432`.
</ParamField>

<ParamField body="ssl" type="boolean">
  Whether to use SSL for the connection. Defaults to `true`.
</ParamField>

<ParamField body="ipv6" type="boolean">
  Whether to use IPv6 for the connection. Defaults to `false`.
</ParamField>

<ParamField body="primary" type="object">
  Connection details for the primary database, only needed when connecting to a replica.

  <Expandable title="primary properties">
    <ParamField body="hostname" type="string" required>
      The primary database server hostname.
    </ParamField>

    <ParamField body="database" type="string" required>
      The name of the logical database in the primary Postgres instance.
    </ParamField>

    <ParamField body="username" type="string" required>
      The primary database username.
    </ParamField>

    <ParamField body="password" type="string" required>
      The primary database password.
    </ParamField>

    <ParamField body="port" type="integer">
      The primary database server port. Defaults to `5432`.
    </ParamField>

    <ParamField body="ssl" type="boolean">
      Whether to use SSL for the primary connection. Defaults to `true`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="replication_slots" type="array" required={true}>
  <Expandable title="properties" defaultOpen={true}>
    <ParamField body="publication_name" type="string" required>
      The name of the publication to use for this replication slot.
    </ParamField>

    <ParamField body="slot_name" type="string" required>
      The name of the replication slot.
    </ParamField>

    <ParamField body="status" type="string">
      The replication slot status. Possible values: `active`, `disabled`. Defaults to `active`.
    </ParamField>
  </Expandable>
</ParamField>

### Response

A database object is returned in the response.

<Expandable title="properties" defaultOpen={false}>
  <ResponseField name="id" type="string (uuid)">
    The ID of the database connection.
  </ResponseField>

  <ResponseField name="name" type="string">
    The user-defined name for the database connection.
  </ResponseField>

  <ResponseField name="hostname" type="string">
    The hostname of the database server.
  </ResponseField>

  <ResponseField name="port" type="integer">
    The port number for the database connection.
  </ResponseField>

  <ResponseField name="database" type="string">
    The name of the logical Postgres database to connect to.
  </ResponseField>

  <ResponseField name="username" type="string">
    The username for authenticating with the database.
  </ResponseField>

  <ResponseField name="password" type="string">
    The password for authenticating with the database. This will be obfuscated unless `show_sensitive=true` is used.
  </ResponseField>

  <ResponseField name="ssl" type="boolean">
    Indicates whether SSL is enabled for the connection.
  </ResponseField>

  <ResponseField name="ipv6" type="boolean">
    Indicates whether the hostname resolves to an IPv6 address.
  </ResponseField>

  <ResponseField name="use_local_tunnel" type="boolean">
    Indicates whether this database connection uses the [Sequin local tunnel](/reference/cli#tunnel-sequin-cloud-only).
  </ResponseField>

  <ResponseField name="pool_size" type="integer">
    Database connection pool size (internal setting).
  </ResponseField>

  <ResponseField name="queue_interval" type="integer">
    Database connection pool queue interval (internal setting).
  </ResponseField>

  <ResponseField name="queue_target" type="integer">
    Database connection pool queue target (internal setting).
  </ResponseField>

  <ResponseField name="replication_slots" type="array">
    Details about the associated replication slot. Will be an empty array if no slot exists.

    <Expandable title="properties" defaultOpen={true}>
      <ResponseField name="id" type="string (uuid)">
        The ID of the replication slot.
      </ResponseField>

      <ResponseField name="publication_name" type="string">
        The name of the Postgres publication used for replication.
      </ResponseField>

      <ResponseField name="slot_name" type="string">
        The name of the Postgres replication slot.
      </ResponseField>

      <ResponseField name="status" type="string (enum: active | disabled)">
        The current status of the replication slot.
      </ResponseField>
    </Expandable>
  </ResponseField>
</Expandable>

<RequestExample>
  ```bash Using URL theme={null}
  curl --request POST \
    --url https://api.sequinstream.com/api/postgres_databases \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --data '{
      "name": "example-db",
      "url": "postgresql://postgres:secret-password@db.example.com:5432/postgres",
      "ssl": true,
      "replication_slots": [
        {
          "publication_name": "sequin_pub",
          "slot_name": "sequin_slot"
        }
      ]
    }'
  ```

  ```bash Using connection params theme={null}
  curl --request POST \
    --url https://api.sequinstream.com/api/postgres_databases \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --data '{
      "name": "example-db",
      "hostname": "db.example.com",
      "database": "postgres",
      "username": "postgres",
      "password": "secret-password",
      "port": 5432,
      "ssl": true,
      "replication_slots": [
        {
          "publication_name": "sequin_pub",
          "slot_name": "sequin_slot"
        }
      ]
    }'
  ```

  ```bash Connecting to a replica theme={null}
  curl --request POST \
    --url https://api.sequinstream.com/api/postgres_databases \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --data '{
      "name": "replica-db",
      "hostname": "replica.example.com",
      "database": "postgres",
      "username": "postgres",
      "password": "replica-password",
      "port": 5432,
      "ssl": true,
      "primary": {
        "hostname": "primary.example.com",
        "database": "postgres",
        "username": "postgres",
        "password": "primary-password",
        "port": 5432,
        "ssl": true
      },
      "replication_slots": [
        {
          "publication_name": "sequin_pub",
          "slot_name": "sequin_slot"
        }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "db_01HRMW3ZNE5EFGW9SDXW01TT92",
    "name": "example-db",
    "hostname": "db.example.com",
    "database": "postgres",
    "username": "postgres",
    "password": "************",
    "port": 5432,
    "ssl": true,
    "use_local_tunnel": false,
    "ipv6": false,
    "replication_slots": [
      {
        "id": "rs_01HRMW3ZNE5EFGW9SDXW01TT93",
        "publication_name": "sequin_pub",
        "slot_name": "sequin_slot",
        "status": "active"
      }
    ]
  }
  ```
</ResponseExample>