{
    "mode": "man",
    "parameter": "CREATE_SUBSCRIPTION",
    "section": "7",
    "url": "https://www.chedong.com/phpMan.php/man/CREATE_SUBSCRIPTION/7/json",
    "generated": "2026-10-04T13:49:10Z",
    "synopsis": "CREATE SUBSCRIPTION subscriptionname\nCONNECTION 'conninfo'\nPUBLICATION publicationname [, ...]\n[ WITH ( subscriptionparameter [= value] [, ... ] ) ]",
    "sections": {
        "NAME": {
            "content": "CREATESUBSCRIPTION - define a new subscription\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "CREATE SUBSCRIPTION subscriptionname\nCONNECTION 'conninfo'\nPUBLICATION publicationname [, ...]\n[ WITH ( subscriptionparameter [= value] [, ... ] ) ]\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "CREATE SUBSCRIPTION adds a new logical-replication subscription. The user that creates a\nsubscription becomes the owner of the subscription. The subscription name must be distinct\nfrom the name of any existing subscription in the current database.\n\nA subscription represents a replication connection to the publisher. Hence, in addition to\nadding definitions in the local catalogs, this command normally creates a replication slot on\nthe publisher.\n\nA logical replication worker will be started to replicate data for the new subscription at\nthe commit of the transaction where this command is run, unless the subscription is initially\ndisabled.\n\nTo be able to create a subscription, you must have the privileges of the the\npgcreatesubscription role, as well as CREATE privileges on the current database.\n\nAdditional information about subscriptions and logical replication as a whole is available at\nSection 31.2 and Chapter 31.\n",
            "subsections": []
        },
        "PARAMETERS": {
            "content": "subscriptionname\nThe name of the new subscription.\n\nCONNECTION 'conninfo'\nThe libpq connection string defining how to connect to the publisher database. For\ndetails see Section 34.1.1.\n\nPUBLICATION publicationname [, ...]\nNames of the publications on the publisher to subscribe to.\n\nWITH ( subscriptionparameter [= value] [, ... ] )\nThis clause specifies optional parameters for a subscription.\n\nThe following parameters control what happens during subscription creation:\n\nconnect (boolean)\nSpecifies whether the CREATE SUBSCRIPTION command should connect to the publisher at\nall. The default is true. Setting this to false will force the values of createslot,\nenabled and copydata to false. (You cannot combine setting connect to false with\nsetting createslot, enabled, or copydata to true.)\n\nSince no connection is made when this option is false, no tables are subscribed. To\ninitiate replication, you must manually create the replication slot, enable the\nsubscription, and refresh the subscription. See Section 31.2.3 for examples.\n\ncreateslot (boolean)\nSpecifies whether the command should create the replication slot on the publisher.\nThe default is true.\n\nIf set to false, you are responsible for creating the publisher's slot in some other\nway. See Section 31.2.3 for examples.\n\nenabled (boolean)\nSpecifies whether the subscription should be actively replicating or whether it\nshould just be set up but not started yet. The default is true.\n\nslotname (string)\nName of the publisher's replication slot to use. The default is to use the name of\nthe subscription for the slot name.\n\nSetting slotname to NONE means there will be no replication slot associated with the\nsubscription. Such subscriptions must also have both enabled and createslot set to\nfalse. Use this when you will be creating the replication slot later manually. See\nSection 31.2.3 for examples.\n\nThe following parameters control the subscription's replication behavior after it has\nbeen created:\n\nbinary (boolean)\nSpecifies whether the subscription will request the publisher to send the data in\nbinary format (as opposed to text). The default is false. Any initial table\nsynchronization copy (see copydata) also uses the same format. Binary format can be\nfaster than the text format, but it is less portable across machine architectures and\nPostgreSQL versions. Binary format is very data type specific; for example, it will\nnot allow copying from a smallint column to an integer column, even though that would\nwork fine in text format. Even when this option is enabled, only data types having\nbinary send and receive functions will be transferred in binary. Note that the\ninitial synchronization requires all data types to have binary send and receive\nfunctions, otherwise the synchronization will fail (see CREATE TYPE (CREATETYPE(7))\nfor more about send/receive functions).\n\nWhen doing cross-version replication, it could be that the publisher has a binary\nsend function for some data type, but the subscriber lacks a binary receive function\nfor that type. In such a case, data transfer will fail, and the binary option cannot\nbe used.\n\nIf the publisher is a PostgreSQL version before 16, then any initial table\nsynchronization will use text format even if binary = true.\n\ncopydata (boolean)\nSpecifies whether to copy pre-existing data in the publications that are being\nsubscribed to when the replication starts. The default is true.\n\nIf the publications contain WHERE clauses, it will affect what data is copied. Refer\nto the Notes for details.\n\nSee Notes for details of how copydata = true can interact with the origin parameter.\n\nstreaming (enum)\nSpecifies whether to enable streaming of in-progress transactions for this\nsubscription. The default value is off, meaning all transactions are fully decoded on\nthe publisher and only then sent to the subscriber as a whole.\n\nIf set to on, the incoming changes are written to temporary files and then applied\nonly after the transaction is committed on the publisher and received by the\nsubscriber.\n\nIf set to parallel, incoming changes are directly applied via one of the parallel\napply workers, if available. If no parallel apply worker is free to handle streaming\ntransactions then the changes are written to temporary files and applied after the\ntransaction is committed. Note that if an error happens in a parallel apply worker,\nthe finish LSN of the remote transaction might not be reported in the server log.\n\nsynchronouscommit (enum)\nThe value of this parameter overrides the synchronouscommit setting within this\nsubscription's apply worker processes. The default value is off.\n\nIt is safe to use off for logical replication: If the subscriber loses transactions\nbecause of missing synchronization, the data will be sent again from the publisher.\n\nA different setting might be appropriate when doing synchronous logical replication.\nThe logical replication workers report the positions of writes and flushes to the\npublisher, and when using synchronous replication, the publisher will wait for the\nactual flush. This means that setting synchronouscommit for the subscriber to off\nwhen the subscription is used for synchronous replication might increase the latency\nfor COMMIT on the publisher. In this scenario, it can be advantageous to set\nsynchronouscommit to local or higher.\n\ntwophase (boolean)\nSpecifies whether two-phase commit is enabled for this subscription. The default is\nfalse.\n\nWhen two-phase commit is enabled, prepared transactions are sent to the subscriber at\nthe time of PREPARE TRANSACTION, and are processed as two-phase transactions on the\nsubscriber too. Otherwise, prepared transactions are sent to the subscriber only when\ncommitted, and are then processed immediately by the subscriber.\n\nThe implementation of two-phase commit requires that replication has successfully\nfinished the initial table synchronization phase. So even when twophase is enabled\nfor a subscription, the internal two-phase state remains temporarily “pending” until\nthe initialization phase completes. See column subtwophasestate of pgsubscription to\nknow the actual two-phase state.\n\ndisableonerror (boolean)\nSpecifies whether the subscription should be automatically disabled if any errors are\ndetected by subscription workers during data replication from the publisher. The\ndefault is false.\n\npasswordrequired (boolean)\nIf set to true, connections to the publisher made as a result of this subscription\nmust use password authentication and the password must be specified as a part of the\nconnection string. This setting is ignored when the subscription is owned by a\nsuperuser. The default is true. Only superusers can set this value to false.\n\nrunasowner (boolean)\nIf true, all replication actions are performed as the subscription owner. If false,\nreplication workers will perform actions on each table as the owner of that table.\nThe latter configuration is generally much more secure; for details, see\nSection 31.9. The default is false.\n\norigin (string)\nSpecifies whether the subscription will request the publisher to only send changes\nthat don't have an origin or send changes regardless of origin. Setting origin to\nnone means that the subscription will request the publisher to only send changes that\ndon't have an origin. Setting origin to any means that the publisher sends changes\nregardless of their origin. The default is any.\n\nSee Notes for details of how copydata = true can interact with the origin parameter.\n\nWhen specifying a parameter of type boolean, the = value part can be omitted, which is\nequivalent to specifying TRUE.\n",
            "subsections": []
        },
        "NOTES": {
            "content": "See Section 31.9 for details on how to configure access control between the subscription and\nthe publication instance.\n\nWhen creating a replication slot (the default behavior), CREATE SUBSCRIPTION cannot be\nexecuted inside a transaction block.\n\nCreating a subscription that connects to the same database cluster (for example, to replicate\nbetween databases in the same cluster or to replicate within the same database) will only\nsucceed if the replication slot is not created as part of the same command. Otherwise, the\nCREATE SUBSCRIPTION call will hang. To make this work, create the replication slot separately\n(using the function pgcreatelogicalreplicationslot with the plugin name pgoutput) and\ncreate the subscription using the parameter createslot = false. See Section 31.2.3 for\nexamples. This is an implementation restriction that might be lifted in a future release.\n\nIf any table in the publication has a WHERE clause, rows for which the expression evaluates\nto false or null will not be published. If the subscription has several publications in which\nthe same table has been published with different WHERE clauses, a row will be published if\nany of the expressions (referring to that publish operation) are satisfied. In the case of\ndifferent WHERE clauses, if one of the publications has no WHERE clause (referring to that\npublish operation) or the publication is declared as FOR ALL TABLES or FOR TABLES IN SCHEMA,\nrows are always published regardless of the definition of the other expressions. If the\nsubscriber is a PostgreSQL version before 15, then any row filtering is ignored during the\ninitial data synchronization phase. For this case, the user might want to consider deleting\nany initially copied data that would be incompatible with subsequent filtering. Because\ninitial data synchronization does not take into account the publication publish parameter\nwhen copying existing table data, some rows may be copied that would not be replicated using\nDML. See Section 31.2.2 for examples.\n\nSubscriptions having several publications in which the same table has been published with\ndifferent column lists are not supported.\n\nWe allow non-existent publications to be specified so that users can add those later. This\nmeans pgsubscription can have non-existent publications.\n\nWhen using a subscription parameter combination of copydata = true and origin = NONE, the\ninitial sync table data is copied directly from the publisher, meaning that knowledge of the\ntrue origin of that data is not possible. If the publisher also has subscriptions then the\ncopied table data might have originated from further upstream. This scenario is detected and\na WARNING is logged to the user, but the warning is only an indication of a potential\nproblem; it is the user's responsibility to make the necessary checks to ensure the copied\ndata origins are really as wanted or not.\n\nTo find which tables might potentially include non-local origins (due to other subscriptions\ncreated on the publisher) try this SQL query:\n\n# substitute <pub-names> below with your publication name(s) to be queried\nSELECT DISTINCT PT.schemaname, PT.tablename\nFROM pgpublicationtables PT\nJOIN pgclass C ON (C.relname = PT.tablename)\nJOIN pgnamespace N ON (N.nspname = PT.schemaname),\npgsubscriptionrel PS\nWHERE C.relnamespace = N.oid AND\n(PS.srrelid = C.oid OR\nC.oid IN (SELECT relid FROM pgpartitionancestors(PS.srrelid) UNION\nSELECT relid FROM pgpartitiontree(PS.srrelid))) AND\nPT.pubname IN (<pub-names>);\n",
            "subsections": []
        },
        "EXAMPLES": {
            "content": "Create a subscription to a remote server that replicates tables in the publications\nmypublication and insertonly and starts replicating immediately on commit:\n\nCREATE SUBSCRIPTION mysub\nCONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'\nPUBLICATION mypublication, insertonly;\n\nCreate a subscription to a remote server that replicates tables in the insertonly\npublication and does not start replicating until enabled at a later time.\n\nCREATE SUBSCRIPTION mysub\nCONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'\nPUBLICATION insertonly\nWITH (enabled = false);\n",
            "subsections": []
        },
        "COMPATIBILITY": {
            "content": "CREATE SUBSCRIPTION is a PostgreSQL extension.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "ALTER SUBSCRIPTION (ALTERSUBSCRIPTION(7)), DROP SUBSCRIPTION (DROPSUBSCRIPTION(7)), CREATE\nPUBLICATION (CREATEPUBLICATION(7)), ALTER PUBLICATION (ALTERPUBLICATION(7))\n\nPostgreSQL 16.14                                2026                          CREATE SUBSCRIPTION(7)",
            "subsections": []
        }
    },
    "summary": "CREATESUBSCRIPTION - define a new subscription",
    "flags": [],
    "examples": [
        "Create a subscription to a remote server that replicates tables in the publications",
        "mypublication and insertonly and starts replicating immediately on commit:",
        "CREATE SUBSCRIPTION mysub",
        "CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'",
        "PUBLICATION mypublication, insertonly;",
        "Create a subscription to a remote server that replicates tables in the insertonly",
        "publication and does not start replicating until enabled at a later time.",
        "CREATE SUBSCRIPTION mysub",
        "CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'",
        "PUBLICATION insertonly",
        "WITH (enabled = false);"
    ],
    "see_also": [
        {
            "name": "ALTERSUBSCRIPTION",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/ALTERSUBSCRIPTION/7/json"
        },
        {
            "name": "DROPSUBSCRIPTION",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/DROPSUBSCRIPTION/7/json"
        },
        {
            "name": "CREATEPUBLICATION",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/CREATEPUBLICATION/7/json"
        },
        {
            "name": "ALTERPUBLICATION",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/ALTERPUBLICATION/7/json"
        },
        {
            "name": "SUBSCRIPTION",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/SUBSCRIPTION/7/json"
        }
    ]
}