supabase/web/spec/postgres.yml

openref: 0.1

info:
  id: reference/postgres
  title: Getting started
  description: |

    PostgreSQL, also known as Postgres, is a free and open-source relational 
    database management system emphasizing extensibility and SQL compliance. 
    It was originally named POSTGRES, referring to its origins as a successor 
    to the Ingres database developed at the University of California, Berkeley.

  definition: spec/combined.json
  libraries:
    - name: 'SQL'
      id: 'sql'
      version: '0.0.1'
  docs:
    path: reference/postgres/
    sidebar:
      - name: 'About'
        items:
          - index
          - Connection Strings
      - name: 'Managing Tables'
        items:
          - Schemas
          - Tables
      # - name: 'Columns'
      #   items:
      #     - Creating columns
          # - Column types
      - name: 'Replication'
        items:
          - Publications
      - name: 'Database Configuration'
        items:
          # - Database Users
          - Database Passwords
          - Changing Timezones

pages:
  Schemas:
    description: |
      Schemas are like "folders". They help to keep your database organized. 

      Schemas are particularly useful for security. You can set different permissions on each schema. 
      For example, you might want to use a `public` schema for user-facing data, and an `auth` schema for all logins and secured data.

    notes: |
      - Schemas contain [tables](/docs/reference/postgres/tables), columns, triggers, functions, etc.
      - Postgres comes with a `public` schema set up by default.
      - It is best practice to use lowercase and underscores when naming schemas. For example: `schema_name`, not `Schema Name`.

    examples:
      - name: Creating a schema
        isSpotlight: true
        sql: |
          ```sql
          create schema schema_name;
          ```
      - name: Removing a schema
        sql: |
          ```sql
          drop schema if exists schema_name;
          ```
      - name: Using special characters
        description: |
          Although it's not recommended, you can use uppercase and spaces when naming your schema by wrapping the name with double-quotes.
          As a result, you will always need to use double-quotes when referencing your schema.
        sql: |
          ```sql
          create schema "Schema Name";
          ```
  Tables:
    description: |
      Tables are similar to excel spreadsheets. They contain columns & rows of data. There are a few key differences from a spreadsheet however:
      
      - Every column is a strict type of data. When you set up a column, you must define what "data type" it is.
      - Tables can be joined together through relationships. For example you can have a "users" table, which is joined to a "teams" table.

    notes: |
      - Tables contain columns, rows, triggers, comments, 
      - It is best practice to use lowercase and underscores when naming tables. For example: `table_name`, not `Table Name`.
      - Tables belong to [schemas](/docs/reference/postgres/schemas). If you don't explicitly pass the schema, Postgres will assume that you want to create the table in the `public` schema.

    examples:
      - name: Create table
        isSpotlight: true
        sql: |
          ```sql
          create table table_name (
            id integer primary key,
            data jsonb,
            name text
          );

          # with schema 
          create table schema_name.table_name (
            id integer primary key,
            data jsonb,
            name text
          );
          ```
      - name: Primary keys using multiple columns
        sql: |
          ```sql
          create table table_name (
            column_1 data_type,
            column_2 data_type
            -- Constraints:
            primary key (column_1, column_2)
          );
          ```
      - name: Multiple foreign keys to the same table
        sql: |
          ```sql
          alter table table_name
            add constraint constraint_name_1 foreign key (column_1) references foreign_table(id),
            add constraint constraint_name_2 foreign key (column_2) references foreign_table(id);
          ```
      - name: Delete a table
        sql: |
          ```sql
          delete table if exists table_name;
          ```
  Columns:
    description: |
      Creating columns.

    examples:
      - name: During table creation
        isSpotlight: true
        sql: |
          ```sql
          create table table_name (
            id integer primary key,
            data jsonb,
            name text
          );
          ```
      - name: Create column
        sql: |
          ```sql
          alter table new_table
          add new_column text;
          ```
  # Data types:
  #   description: |
  #     Data types.

  #   examples:
  #     - name: Create columns and data types
  #       sql: |
  #         ```sql
  #         alter table new_table
  #         add new_column text;
  #         ```

  Publications:
    description: |
      Publications are a way of grouping changes generated from a table or a group of tables. 
      These changes can then be sent to other systems (usually another Postgres database).

    examples:
      - name: Create a Publication
        description: |
          This publication will contain all changes to all tables.
        sql: |
          ```sql
          create publication publication_name 
          for all tables;
          ```
      - name: Create a Publication which listens to individual tables
        sql: |
          ```sql
          create publication publication_name 
          for table table_one, table_two;
          ```
      - name: Add tables to an existing publication
        sql: |
          ```sql
          alter publication publication_name 
          add table table_name;
          ```
      - name: Listens to inserts only
        sql: |
          ```sql
          create publication publication_name 
          for all tables
          with (publish = 'insert');
          ```
      - name: Listens to updates only
        sql: |
          ```sql
          create publication publication_name 
          for all tables
          with (publish = 'update');
          ```
      - name: Listens to deletions only
        sql: |
          ```sql
          create publication publication_name 
          for all tables
          with (publish = 'delete');
          ```
      - name: Remove a Publication
        sql: |
          ```sql
          drop publication if exists publication_name;
          ```
      - name: Recreate a Publication
        description: |
          If you are planning to re-create a publication, it's best to do it in a transaction to ensure the operation succeeds.
        sql: |
          ```sql
          begin; 
            -- remove the realtime publication
            drop publication if exists publication_name; 

            -- re-create the publication but don't enable it for any tables
            create publication publication_name;  
          commit;
          ```
          
  Database Users:
    description: |
      Users and Roles are almost interchangeable.

    examples:
      - name: Create New User
        sql: |
          ```sql
          create user new_user
          with password 'hello';
          ```
  Database Passwords:
    description: |
      Manage the passwords of your database users using any super user.

    examples:
      - name: Password reset
        sql: |
          ```sql
          alter user postgres 
          with password 'new_password';
          ```
  Changing Timezones:
    description: |
      Data types.
    notes: |
      - View a full list of timezones on [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).

    examples:
      - name: Change timezone
        isSpotlight: true
        sql: |
          ```sql
          alter database postgres 
          set timezone to 'America/New_York';
          ```
      - name: Full list of timezones
        description: |
          Get a full list of timezones supported by your database. This will return the following columns:

          - `name`: Time zone name
          - `abbrev`: Time zone abbreviation
          - `utc_offset`: Offset from UTC (positive means east of Greenwich)
          - `is_dst`: True if currently observing daylight savings

        sql: |
          ```sql
          select name, abbrev, utc_offset, is_dst
          from pg_timezone_names() 
          order by name;
          ```
      - name: Search for a specific timezone
        description: Use `ilike` (case insensitive search) to find specific timezones.
        sql: |
          ```sql
          select * 
          from pg_timezone_names() 
          where name ilike '%york%';
          ```

  Connection Strings:
    description: |
      There are various ways to connect to your database, depending on the configuration of your Postgres instance and the tool which you are connecting with.

    notes: |
      - [Official Documentation](https://www.postgresql.org/docs/current/libpq-connect.html).
      - Avoid using special characters usernames and passwords. If you use special characters in a connection URL, you'll need to URL encode any special characters.

    examples:
      - name: Basic connection string
        description: |
          If you're using a default setup, your postgres connection string will likely be in the format: 
          
          `postgres://{user}:{password}@{host}:{port}/{database_name}`

        isSpotlight: true
        sql: |
          ```bash
          postgres://postgres:postgres@localhost:5432/postgres
          # or 
          postgresql://postgres:postgres@localhost:5432/postgres
          ```
      - name: JDBC
        description: See full [documentation](http://jdbc.postgresql.org/documentation/head/connect.html).
        sql: |
          ```bash
          jdbc:postgresql://{host}:{port}/{database_name}
          ```
      - name: ADO.NET
        description: See full [documentation](http://npgsql.projects.postgresql.org/docs/manual/UserManual.html).
        sql: |
          ```bash
          Server=host;Port=5432;User Id=username;Password=secret;Database=database_name;
          ```
      - name: PHP
        description: See full [documentation](http://php.net/manual/en/book.pgsql.php).
        sql: |
          ```bash
          host=hostname port=5432 dbname=databasename user=username password=secret
          ```