{
    "content": [
        {
            "type": "text",
            "text": "# DBD::Proxy (perldoc)\n\n## NAME\n\nDBD::Proxy - A proxy driver for the DBI\n\n## SYNOPSIS\n\nuse DBI;\n$dbh = DBI->connect(\"dbi:Proxy:hostname=$host;port=$port;dsn=$db\",\n$user, $passwd);\n# See the DBI module documentation for full details\n\n## DESCRIPTION\n\nDBD::Proxy is a Perl module for connecting to a database via a remote DBI driver. See DBD::Gofer\nfor an alternative with different trade-offs.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **CONNECTING TO THE DATABASE**\n- **KNOWN ISSUES** (2 subsections)\n- **SECURITY WARNING**\n- **AUTHOR AND COPYRIGHT**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "DBD::Proxy",
        "section": "",
        "mode": "perldoc",
        "summary": "DBD::Proxy - A proxy driver for the DBI",
        "synopsis": "use DBI;\n$dbh = DBI->connect(\"dbi:Proxy:hostname=$host;port=$port;dsn=$db\",\n$user, $passwd);\n# See the DBI module documentation for full details",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 7,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 16,
                "subsections": []
            },
            {
                "name": "CONNECTING TO THE DATABASE",
                "lines": 105,
                "subsections": []
            },
            {
                "name": "KNOWN ISSUES",
                "lines": 1,
                "subsections": [
                    {
                        "name": "Unproxied method calls",
                        "lines": 16
                    },
                    {
                        "name": "Complex handle attributes",
                        "lines": 35
                    }
                ]
            },
            {
                "name": "SECURITY WARNING",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "AUTHOR AND COPYRIGHT",
                "lines": 14,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "DBD::Proxy - A proxy driver for the DBI\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "use DBI;\n\n$dbh = DBI->connect(\"dbi:Proxy:hostname=$host;port=$port;dsn=$db\",\n$user, $passwd);\n\n# See the DBI module documentation for full details\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "DBD::Proxy is a Perl module for connecting to a database via a remote DBI driver. See DBD::Gofer\nfor an alternative with different trade-offs.\n\nThis is of course not needed for DBI drivers which already support connecting to a remote\ndatabase, but there are engines which don't offer network connectivity.\n\nAnother application is offering database access through a firewall, as the driver offers query\nbased restrictions. For example you can restrict queries to exactly those that are used in a\ngiven CGI application.\n\nSpeaking of CGI, another application is (or rather, will be) to reduce the database\nconnect/disconnect overhead from CGI scripts by using proxying the connectcached method. The\nproxy server will hold the database connections open in a cache. The CGI script then trades the\ndatabase connect/disconnect overhead for the DBD::Proxy connect/disconnect overhead which is\ntypically much less.\n",
                "subsections": []
            },
            "CONNECTING TO THE DATABASE": {
                "content": "Before connecting to a remote database, you must ensure, that a Proxy server is running on the\nremote machine. There's no default port, so you have to ask your system administrator for the\nport number. See DBI::ProxyServer for details.\n\nSay, your Proxy server is running on machine \"alpha\", port 3334, and you'd like to connect to an\nODBC database called \"mydb\" as user \"joe\" with password \"hello\". When using DBD::ODBC directly,\nyou'd do a\n\n$dbh = DBI->connect(\"DBI:ODBC:mydb\", \"joe\", \"hello\");\n\nWith DBD::Proxy this becomes\n\n$dsn = \"DBI:Proxy:hostname=alpha;port=3334;dsn=DBI:ODBC:mydb\";\n$dbh = DBI->connect($dsn, \"joe\", \"hello\");\n\nYou see, this is mainly the same. The DBD::Proxy module will create a connection to the Proxy\nserver on \"alpha\" which in turn will connect to the ODBC database.\n\nRefer to the DBI documentation on the \"connect\" method for a way to automatically use DBD::Proxy\nwithout having to change your code.\n\nDBD::Proxy's DSN string has the format\n\n$dsn = \"DBI:Proxy:key1=val1; ... ;keyN=valN;dsn=valDSN\";\n\nIn other words, it is a collection of key/value pairs. The following keys are recognized:\n\nhostname\nport\nHostname and port of the Proxy server; these keys must be present, no defaults. Example:\n\nhostname=alpha;port=3334\n\ndsn The value of this attribute will be used as a dsn name by the Proxy server. Thus it must\nhave the format \"DBI:driver:...\", in particular it will contain colons. The *dsn* value may\ncontain semicolons, hence this key *must* be the last and it's value will be the complete\nremaining part of the dsn. Example:\n\ndsn=DBI:ODBC:mydb\n\ncipher\nkey\nusercipher\nuserkey\nBy using these fields you can enable encryption. If you set, for example,\n\ncipher=$class;key=$key\n\n(note the semicolon) then DBD::Proxy will create a new cipher object by executing\n\n$cipherRef = $class->new(pack(\"H*\", $key));\n\nand pass this object to the RPC::PlClient module when creating a client. See RPC::PlClient.\nExample:\n\ncipher=IDEA;key=97cd2375efa329aceef2098babdc9721\n\nThe usercipher/userkey attributes allow you to use two phase encryption: The cipher/key\nencryption will be used in the login and authorisation phase. Once the client is authorised,\nhe will change to usercipher/userkey encryption. Thus the cipher/key pair is a host based\nsecret, typically less secure than the usercipher/userkey secret and readable by anyone. The\nusercipher/userkey secret is your private secret.\n\nOf course encryption requires an appropriately configured server. See \"CONFIGURATION FILE\"\nin DBD::ProxyServer.\n\ndebug\nTurn on debugging mode\n\nstderr\nThis attribute will set the corresponding attribute of the RPC::PlClient object, thus\nlogging will not use syslog(), but redirected to stderr. This is the default under Windows.\n\nstderr=1\n\nlogfile\nSimilar to the stderr attribute, but output will be redirected to the given file.\n\nlogfile=/dev/null\n\nRowCacheSize\nThe DBD::Proxy driver supports this attribute (which is DBI standard, as of DBI 1.02). It's\nused to reduce network round-trips by fetching multiple rows in one go. The current default\nvalue is 20, but this may change.\n\nproxynofinish\nThis attribute can be used to reduce network traffic: If the application is calling\n$sth->finish() then the proxy tells the server to finish the remote statement handle. Of\ncourse this slows down things quite a lot, but is perfectly good for reducing memory usage\nwith persistent connections.\n\nHowever, if you set the *proxynofinish* attribute to a TRUE value, either in the database\nhandle or in the statement handle, then finish() calls will be suppressed. This is what you\nwant, for example, in small and fast CGI applications.\n\nproxyquote\nThis attribute can be used to reduce network traffic: By default calls to $dbh->quote() are\npassed to the remote driver. Of course this slows down things quite a lot, but is the safest\ndefault behaviour.\n\nHowever, if you set the *proxyquote* attribute to the value '\"local\"' either in the\ndatabase handle or in the statement handle, and the call to quote has only one parameter,\nthen the local default DBI quote method will be used (which will be faster but may be\nwrong).\n",
                "subsections": []
            },
            "KNOWN ISSUES": {
                "content": "",
                "subsections": [
                    {
                        "name": "Unproxied method calls",
                        "content": "If a method isn't being proxied, try declaring a stub sub in the appropriate package\n(DBD::Proxy::db for a dbh method, and DBD::Proxy::st for an sth method). For example:\n\nsub DBD::Proxy::db::selectallarrayref;\n\nThat will enable selectallarrayref to be proxied.\n\nCurrently many methods aren't explicitly proxied and so you get the DBI's default methods\nexecuted on the client.\n\nSome of those methods, like selectallarrayref, may then call other methods that are proxied\n(selectallarrayref calls fetchallarrayref which calls fetch which is proxied). So things may\nappear to work but operate more slowly than the could.\n\nThis may all change in a later version.\n"
                    },
                    {
                        "name": "Complex handle attributes",
                        "content": "Sometimes handles are having complex attributes like hash refs or array refs and not simple\nstrings or integers. For example, with DBD::CSV, you would like to write something like\n\n$dbh->{\"csvtables\"}->{\"passwd\"} =\n{ \"sepchar\" => \":\", \"eol\" => \"\\n\";\n\nThe above example would advice the CSV driver to assume the file \"passwd\" to be in the format of\nthe /etc/passwd file: Colons as separators and a line feed without carriage return as line\nterminator.\n\nSurprisingly this example doesn't work with the proxy driver. To understand the reasons, you\nshould consider the following: The Perl compiler is executing the above example in two steps:\n\n1   The first step is fetching the value of the key \"csvtables\" in the handle $dbh. The value\nreturned is complex, a hash ref.\n\n2   The second step is storing some value (the right hand side of the assignment) as the key\n\"passwd\" in the hash ref from step 1.\n\nThis becomes a little bit clearer, if we rewrite the above code:\n\n$tables = $dbh->{\"csvtables\"};\n$tables->{\"passwd\"} = { \"sepchar\" => \":\", \"eol\" => \"\\n\";\n\nWhile the examples work fine without the proxy, the fail due to a subtle difference in step 1:\nBy DBI magic, the hash ref $dbh->{'csvtables'} is returned from the server to the client. The\nclient creates a local copy. This local copy is the result of step 1. In other words, step 2\nmodifies a local copy of the hash ref, but not the server's hash ref.\n\nThe workaround is storing the modified local copy back to the server:\n\n$tables = $dbh->{\"csvtables\"};\n$tables->{\"passwd\"} = { \"sepchar\" => \":\", \"eol\" => \"\\n\";\n$dbh->{\"csvtables\"} = $tables;\n"
                    }
                ]
            },
            "SECURITY WARNING": {
                "content": "RPC::PlClient used underneath is not secure due to serializing and deserializing data with\nStorable module. Use the proxy driver only in trusted environment.\n",
                "subsections": []
            },
            "AUTHOR AND COPYRIGHT": {
                "content": "This module is Copyright (c) 1997, 1998\n\nJochen Wiedmann\nAm Eisteich 9\n72555 Metzingen\nGermany\n\nEmail: joe@ispsoft.de\nPhone: +49 7123 14887\n\nThe DBD::Proxy module is free software; you can redistribute it and/or modify it under the same\nterms as Perl itself. In particular permission is granted to Tim Bunce for distributing this as\na part of the DBI.\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "DBI, RPC::PlClient, Storable\n",
                "subsections": []
            }
        }
    }
}