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

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;
  #         ```
          
  Database Users:
    description: |
      Users and Roles are almost interchangeable.

    examples:
      - name: Create New User
        sql: |
          ```sql
          create user new_user
          with password 'hello';
          ```