# API documentation

This chapter briefly explains some implementation detail.

class pglast.Comment(location, text, at_start_of_line, continue_previous)

  A structure to carry information about a single SQL comment.

  at_start_of_line

    Alias for field number 2

  continue_previous

    Alias for field number 3

  location

    Alias for field number 0

  text

    Alias for field number 1

exception pglast.Error

  Top level error exception.

pglast.__author__ = 'Lele Gaifax <lele@metapensiero.it>'

  Package’s author.

pglast.__version__ = 'v7.5'

  Package’s version.

pglast.parse_plpgsql(statement)

  Parse the given `PLPGSQL` statement and return its tokens stream.

  Note

  This is currently somewhat of limited usefulness, because neither `libpg_query` [1] nor `pglast` expose proper `AST` nodes for the PostgreSQL’s procedural extension language, and thus it returns the raw tree, represented by plain Python structures such as lists, dictionaries and scalar values.

  Consider the following examples, two different ways to parse the same `SQL` statement. The first uses `parse_plpgsql()`:

      from pprint import pprint
      from pglast import parse_plpgsql

      STMT = '''\
      CREATE FUNCTION add (a integer, b integer)
      RETURNS integer AS $$
      BEGIN
        RETURN a + b;
      END;
      $$ LANGUAGE plpgsql
      '''

      as_plpgsql = parse_plpgsql(STMT)
      pprint(as_plpgsql, depth=6)

  and emits this structure:

      [{'PLpgSQL_function': {'action': {'PLpgSQL_stmt_block': {'body': [{...}],
                                                               'lineno': 2}},
                             'datums': [{'PLpgSQL_var': {'datatype': {...},
                                                         'refname': 'a'}},
                                        {'PLpgSQL_var': {'datatype': {...},
                                                         'refname': 'b'}},
                                        {'PLpgSQL_var': {'datatype': {...},
                                                         'refname': 'found'}}]}}]

  As you can see, is just a list of plain Python dictionaries, more or less representing syntax tokens.

  If you use `parse_sql()` instead:

      from pglast import parse_sql

      as_sql = parse_sql(STMT)
      pprint([stmt(skip_none=True) for stmt in as_sql])

  you obtain a richer representation[2] of the statement:

      [{'@': 'RawStmt',
        'stmt': {'@': 'CreateFunctionStmt',
                 'funcname': ({'@': 'String', 'sval': 'add'},),
                 'is_procedure': False,
                 'options': ({'@': 'DefElem',
                              'arg': ({'@': 'String',
                                       'sval': '\nBEGIN\n  RETURN a + b;\nEND;\n'},),
                              'defaction': {'#': 'DefElemAction',
                                            'name': 'DEFELEM_UNSPEC',
                                            'value': 0},
                              'defname': 'as',
                              'location': ...},
                             {'@': 'DefElem',
                              'arg': {'@': 'String', 'sval': 'plpgsql'},
                              'defaction': {'#': 'DefElemAction',
                                            'name': 'DEFELEM_UNSPEC',
                                            'value': 0},
                              'defname': 'language',
                              'location': ...}),
                 'parameters': ({'@': 'FunctionParameter',
                                 'argType': {'@': 'TypeName',
                                             'location': ...,
                                             'names': ({'@': 'String',
                                                        'sval': 'pg_catalog'},
                                                       {'@': 'String',
                                                        'sval': 'int4'}),
                                             'pct_type': False,
                                             'setof': False,
                                             'typemod': -1},
                                 'mode': {'#': 'FunctionParameterMode',
                                          'name': 'FUNC_PARAM_DEFAULT',
                                          'value': 'd'},
                                 'name': 'a'},
                                {'@': 'FunctionParameter',
                                 'argType': {'@': 'TypeName',
                                             'location': ...,
                                             'names': ({'@': 'String',
                                                        'sval': 'pg_catalog'},
                                                       {'@': 'String',
                                                        'sval': 'int4'}),
                                             'pct_type': False,
                                             'setof': False,
                                             'typemod': -1},
                                 'mode': {'#': 'FunctionParameterMode',
                                          'name': 'FUNC_PARAM_DEFAULT',
                                          'value': 'd'},
                                 'name': 'b'}),
                 'replace': False,
                 'returnType': {'@': 'TypeName',
                                'location': ...,
                                'names': ({'@': 'String', 'sval': 'pg_catalog'},
                                          {'@': 'String', 'sval': 'int4'}),
                                'pct_type': False,
                                'setof': False,
                                'typemod': -1}},
        'stmt_len': 0,
        'stmt_location': 0}]

  [1]

  See also https://github.com/pganalyze/libpg_query/issues/110.

  [2]

  `location` values has been masqueraded for test purposes.

pglast.prettify(statement, safety_belt=False, preserve_comments=False, **options)

  Render given statement into a prettified format.

  Parameters:

    - statement (str) – the SQL statement(s)

    - safety_belt (bool) – whether to perform a safe check against bugs in pglast’s serialization

    - preserve_comments (bool) – whether comments shall be preserved, defaults to not

    - **options – any keyword option accepted by `IndentedStream` constructor

  Returns:

    a string with the equivalent prettified statement(s)

  When safety_belt is `True`, the resulting statement is parsed again and its AST compared with the original statement: if they don’t match, a warning is emitted and the original statement is returned. By default it is `False`, so no double check is done.

pglast.split(stmts, with_parser=True, only_slices=False)

  Split the given stmts string into a sequence of the single `SQL` statements.

  By default this uses the parser to perform the job; when with_parser is `False` the scanner variant is used, indicated when the statements may contain parse errors.

  When only_slices is `True`, return a sequence of `slice` instances, one for each statement, instead of statements text.

  NB: leading and trailing whitespace are removed from the statements.

Packages

- `pglast.parser` — The interface with libpg_query
  - `LONG_MAX`
  - `ParseError`
  - `DeparseError`
  - `Displacements`
  - `deparse_protobuf()`
  - `fingerprint()`
  - `get_postgresql_version()`
  - `parse_sql()`
  - `parse_sql_json()`
  - `parse_sql_protobuf()`
  - `parse_plpgsql_json()`
  - `scan()`
  - `split()`
- `pglast.ast` — Python classes representing PG parser nodes
  - `Node`
  - `A_ArrayExpr`
  - `A_Const`
  - `A_Expr`
  - `A_Indices`
  - `A_Indirection`
  - `A_Star`
  - `AccessPriv`
  - `Aggref`
  - `Alias`
  - `AlterCollationStmt`
  - `AlterDatabaseRefreshCollStmt`
  - `AlterDatabaseSetStmt`
  - `AlterDatabaseStmt`
  - `AlterDefaultPrivilegesStmt`
  - `AlterDomainStmt`
  - `AlterEnumStmt`
  - `AlterEventTrigStmt`
  - `AlterExtensionContentsStmt`
  - `AlterExtensionStmt`
  - `AlterFdwStmt`
  - `AlterForeignServerStmt`
  - `AlterFunctionStmt`
  - `AlterObjectDependsStmt`
  - `AlterObjectSchemaStmt`
  - `AlterOpFamilyStmt`
  - `AlterOperatorStmt`
  - `AlterOwnerStmt`
  - `AlterPolicyStmt`
  - `AlterPublicationStmt`
  - `AlterRoleSetStmt`
  - `AlterRoleStmt`
  - `AlterSeqStmt`
  - `AlterStatsStmt`
  - `AlterSubscriptionStmt`
  - `AlterSystemStmt`
  - `AlterTSConfigurationStmt`
  - `AlterTSDictionaryStmt`
  - `AlterTableCmd`
  - `AlterTableMoveAllStmt`
  - `AlterTableSpaceOptionsStmt`
  - `AlterTableStmt`
  - `AlterTypeStmt`
  - `AlterUserMappingStmt`
  - `AlternativeSubPlan`
  - `ArrayCoerceExpr`
  - `ArrayExpr`
  - `BitString`
  - `BoolExpr`
  - `Boolean`
  - `BooleanTest`
  - `CTECycleClause`
  - `CTESearchClause`
  - `CallContext`
  - `CallStmt`
  - `CaseExpr`
  - `CaseTestExpr`
  - `CaseWhen`
  - `CheckPointStmt`
  - `ClosePortalStmt`
  - `ClusterStmt`
  - `CoalesceExpr`
  - `CoerceToDomain`
  - `CoerceToDomainValue`
  - `CoerceViaIO`
  - `CollateClause`
  - `CollateExpr`
  - `ColumnDef`
  - `ColumnRef`
  - `CommentStmt`
  - `CommonTableExpr`
  - `CompositeTypeStmt`
  - `Constraint`
  - `ConstraintsSetStmt`
  - `ConvertRowtypeExpr`
  - `CopyStmt`
  - `CreateAmStmt`
  - `CreateCastStmt`
  - `CreateConversionStmt`
  - `CreateDomainStmt`
  - `CreateEnumStmt`
  - `CreateEventTrigStmt`
  - `CreateExtensionStmt`
  - `CreateFdwStmt`
  - `CreateForeignServerStmt`
  - `CreateForeignTableStmt`
  - `CreateFunctionStmt`
  - `CreateOpClassItem`
  - `CreateOpClassStmt`
  - `CreateOpFamilyStmt`
  - `CreatePLangStmt`
  - `CreatePolicyStmt`
  - `CreatePublicationStmt`
  - `CreateRangeStmt`
  - `CreateRoleStmt`
  - `CreateSchemaStmt`
  - `CreateSeqStmt`
  - `CreateStatsStmt`
  - `CreateStmt`
  - `CreateSubscriptionStmt`
  - `CreateTableAsStmt`
  - `CreateTableSpaceStmt`
  - `CreateTransformStmt`
  - `CreateTrigStmt`
  - `CreateUserMappingStmt`
  - `CreatedbStmt`
  - `CurrentOfExpr`
  - `DeallocateStmt`
  - `DeclareCursorStmt`
  - `DefElem`
  - `DefineStmt`
  - `DeleteStmt`
  - `DiscardStmt`
  - `DoStmt`
  - `DropOwnedStmt`
  - `DropRoleStmt`
  - `DropStmt`
  - `DropSubscriptionStmt`
  - `DropTableSpaceStmt`
  - `DropUserMappingStmt`
  - `DropdbStmt`
  - `ExecuteStmt`
  - `ExplainStmt`
  - `FetchStmt`
  - `FieldSelect`
  - `FieldStore`
  - `Float`
  - `FromExpr`
  - `FuncCall`
  - `FuncExpr`
  - `FunctionParameter`
  - `GrantRoleStmt`
  - `GrantStmt`
  - `GroupingFunc`
  - `GroupingSet`
  - `ImportForeignSchemaStmt`
  - `IndexElem`
  - `IndexStmt`
  - `InferClause`
  - `InferenceElem`
  - `InlineCodeBlock`
  - `InsertStmt`
  - `Integer`
  - `IntoClause`
  - `JoinExpr`
  - `JsonAggConstructor`
  - `JsonArgument`
  - `JsonArrayAgg`
  - `JsonArrayConstructor`
  - `JsonArrayQueryConstructor`
  - `JsonBehavior`
  - `JsonConstructorExpr`
  - `JsonExpr`
  - `JsonFormat`
  - `JsonFuncExpr`
  - `JsonIsPredicate`
  - `JsonKeyValue`
  - `JsonObjectAgg`
  - `JsonObjectConstructor`
  - `JsonOutput`
  - `JsonParseExpr`
  - `JsonReturning`
  - `JsonScalarExpr`
  - `JsonSerializeExpr`
  - `JsonTable`
  - `JsonTableColumn`
  - `JsonTablePathSpec`
  - `JsonValueExpr`
  - `ListenStmt`
  - `LoadStmt`
  - `LockStmt`
  - `LockingClause`
  - `MergeAction`
  - `MergeStmt`
  - `MergeSupportFunc`
  - `MergeWhenClause`
  - `MinMaxExpr`
  - `MultiAssignRef`
  - `NamedArgExpr`
  - `NotifyStmt`
  - `NullTest`
  - `ObjectWithArgs`
  - `OnConflictClause`
  - `OnConflictExpr`
  - `OpExpr`
  - `PLAssignStmt`
  - `Param`
  - `ParamRef`
  - `PartitionBoundSpec`
  - `PartitionCmd`
  - `PartitionElem`
  - `PartitionRangeDatum`
  - `PartitionSpec`
  - `PrepareStmt`
  - `PublicationObjSpec`
  - `PublicationTable`
  - `Query`
  - `RTEPermissionInfo`
  - `RangeFunction`
  - `RangeSubselect`
  - `RangeTableFunc`
  - `RangeTableFuncCol`
  - `RangeTableSample`
  - `RangeTblEntry`
  - `RangeTblFunction`
  - `RangeTblRef`
  - `RangeVar`
  - `RawStmt`
  - `ReassignOwnedStmt`
  - `RefreshMatViewStmt`
  - `ReindexStmt`
  - `RelabelType`
  - `RenameStmt`
  - `ReplicaIdentityStmt`
  - `ResTarget`
  - `ReturnStmt`
  - `RoleSpec`
  - `RowCompareExpr`
  - `RowExpr`
  - `RowMarkClause`
  - `RuleStmt`
  - `SQLValueFunction`
  - `ScalarArrayOpExpr`
  - `SecLabelStmt`
  - `SelectStmt`
  - `SetOperationStmt`
  - `SetToDefault`
  - `SinglePartitionSpec`
  - `SortBy`
  - `SortGroupClause`
  - `StatsElem`
  - `String`
  - `SubLink`
  - `SubPlan`
  - `SubscriptingRef`
  - `TableFunc`
  - `TableLikeClause`
  - `TableSampleClause`
  - `TargetEntry`
  - `TransactionStmt`
  - `TriggerTransition`
  - `TruncateStmt`
  - `TypeCast`
  - `TypeName`
  - `UnlistenStmt`
  - `UpdateStmt`
  - `VacuumRelation`
  - `VacuumStmt`
  - `Var`
  - `VariableSetStmt`
  - `VariableShowStmt`
  - `ViewStmt`
  - `WindowClause`
  - `WindowDef`
  - `WindowFunc`
  - `WindowFuncRunCondition`
  - `WithCheckOption`
  - `WithClause`
  - `XmlExpr`
  - `XmlSerialize`
- `pglast.enums` — Enumerated constants
  - From `include/catalog`
  - From `include/nodes`
  - From `include/storage`
  - From `include/utils`
- `pglast.keywords` — Various kinds of PostgreSQL keywords
  - `COL_NAME_KEYWORDS`
  - `RESERVED_KEYWORDS`
  - `TYPE_FUNC_NAME_KEYWORDS`
  - `UNRESERVED_KEYWORDS`
- `pglast.stream` — The serialization machinery
  - `OutputStream`
  - `RawStream`
  - `IndentedStream`
- `pglast.printers` — Specialized printer functions
  - `NODE_PRINTERS`
  - `SPECIAL_FUNCTIONS`
  - `PrinterAlreadyPresentError`
  - `get_printer_for_node()`
  - `node_printer()`
  - `special_function()`
  - `pglast.printers.ddl` — DDL printer functions
  - `pglast.printers.dml` — DML printer functions
- `pglast.printers.sfuncs` — Special function printers
  - `btrim()`
  - `extract()`
  - `ltrim()`
  - `normalize()`
  - `overlaps()`
  - `overlay()`
  - `pg_collation_for()`
  - `position()`
  - `rtrim()`
  - `substring()`
  - `timezone()`
  - `xmlexists()`
- `pglast.visitors` — Other ways to inspect and manipulate the AST
  - `Action`
  - `ActionMeta`
  - `Add`
  - `Ancestor`
  - `Continue`
  - `Delete`
  - `ReferencedRelations`
  - `Skip`
  - `Visitor`
  - `referenced_relations()`